Quickstart

This guide takes you from zero to your first authenticated API response. It uses the Market Data API because its endpoints are read-only, but the same steps apply to every Openmarkets API.

1. Request sandbox access

Sandbox credentials are issued by Openmarkets as part of onboarding, so the first step is to get in touch with us.

Contact us with your organisation details and the APIs you intend to use.
We provision your sandbox client and send you its client_id and client_secret.

Access is granted per organisation, and your credentials are issued with the scopes agreed during onboarding. To add an API later, contact us again and we will extend your existing client.

2. Check your credentials and scopes

Keep the client_secret somewhere safe. Treat it like a password and never ship it in client-side code.

Each API requires a specific scope on the token. For this guide you need market-data-api, which must be one of the scopes issued to your client. The full list is in Authentication.

3. Request an access token

Exchange your credentials for a bearer token using the OAuth2 client credentials grant.

curl -X POST 'https://stage-identity.openmarkets.com.au/connect/token' \
  -u '{client_id}:{client_secret}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&scope=market-data-api'

var client = new HttpClient();
var credentials = Convert.ToBase64String(
    Encoding.ASCII.GetBytes($"{clientId}:{clientSecret}"));

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Basic", credentials);

var body = new StringContent(
    "grant_type=client_credentials&scope=market-data-api",
    Encoding.UTF8,
    "application/x-www-form-urlencoded");

var response = await client.PostAsync(
    "https://stage-identity.openmarkets.com.au/connect/token", body);

var json = await response.Content.ReadAsStringAsync();

const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64')

const response = await fetch('https://stage-identity.openmarkets.com.au/connect/token', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    scope: 'market-data-api',
  }),
})

const { access_token: accessToken } = await response.json()

import requests

response = requests.post(
    "https://stage-identity.openmarkets.com.au/connect/token",
    auth=(client_id, client_secret),
    data={
        "grant_type": "client_credentials",
        "scope": "market-data-api",
    },
)

access_token = response.json()["access_token"]

A successful request returns a JWT bearer token (truncated here for readability) and the scopes it was granted:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkIzMzk2NDk4RUM2Njc3QkZBMjVFRkVENzA1RUQ5OTQ0IiwidHlwIjoiYXQrand0In0.eyJpc3MiOiJodHRwczovL2lkZW50aXR5Lm9wZW5tYXJrZXRzLmNvbS5hdS8iLCJuYmYiOjE3ODgyMTg0OTksImlhdCI6MTc4ODIxODQ5OSwiZXhwIjoxNzg4MjIyMDk5LCJhdWQiOlsibWFya2V0LWRhdGEtYXBpIiwiaHR0cHM6Ly9pZGVudGl0eS5vcGVubWFya2V0cy5jb20uYXUvcmVzb3VyY2VzIl0sInNjb3BlIjpbIm1hcmtldC1kYXRhLWFwaSJdLCJjbGllbnRfaWQiOiJkZW1vLWZyb250ZW5kIiwiY2xpZW50X2FhdCI6IjE3MTAyMDE0MDEiLCJjbGllbnRfYnVzaW5lc3NfaWQiOiIxIn0.NFkQ0cI5C5sWiu23wPso297Ywoi8M2njO1N-4hcQeP70NlJx1BpW87wXpL_SlUR6...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "market-data-api"
}

Cache the token for the duration given by expires_in and reuse it. Requesting a new token for every call is the most common cause of unexpected throttling.

4. Make your first call

Send the token as a bearer credential. This endpoint returns the exchanges available to you.

curl 'https://test-market-data-api.openmarkets.com.au/exchanges/information/v1' \
  -H 'Authorization: Bearer {access_token}'

var api = new HttpClient
{
    BaseAddress = new Uri("https://test-market-data-api.openmarkets.com.au/")
};

api.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

var exchanges = await api.GetStringAsync("exchanges/information/v1");

const exchanges = await fetch(
  'https://test-market-data-api.openmarkets.com.au/exchanges/information/v1',
  { headers: { Authorization: `Bearer ${accessToken}` } },
).then((r) => r.json())

exchanges = requests.get(
    "https://test-market-data-api.openmarkets.com.au/exchanges/information/v1",
    headers={"Authorization": f"Bearer {access_token}"},
).json()

If the response is a 403, your token is missing the market-data-api scope. See Market Data errors for the full list of error codes.

Next steps

Market Data APIBase URLs, conventions, rate limits and what the API covers. Place an orderMove from reading market data to sending orders.

Introduction

Authentication