Skip to main content

Authentication

The Multi-Market API uses OAuth 2.0 bearer tokens. Your server exchanges a client ID and secret for a short-lived access token, then sends that token on every request.

Credentials​

When we enable the Multi-Market API for your firm, we issue for each environment (UAT and Production):

ItemPurpose
Token URLWhere you request access tokens
Client IDIdentifies your integration
Client secretProves your integration's identity. Keep it on your servers only

Your client is granted read access, plus trading access if approved, and access to specific accounts. Accounts lists the accounts it can use.

Keep the secret server-side

Never ship the client secret in a mobile app, browser code or a public repository. If it leaks, contact our team to rotate it.

Request an Access Token​

Call the token URL with the client credentials grant:

curl -X POST "$TOKEN_URL" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d grant_type=client_credentials \
-d client_id="$CLIENT_ID" \
-d client_secret="$CLIENT_SECRET"

If our team asks you to request specific scopes, add -d scope="<scopes>" with the values they give you.

A successful response looks like this:

{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 300
}

Call the API​

Send the token in the Authorization header:

curl "https://apac.uat.atomicvaults.com/v2/accounts" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Access tokens are short-lived. Cache the token and request a new one shortly before expires_in elapses, rather than requesting one per API call.

WebSocket Connections​

Open the order-update WebSocket with the same Authorization: Bearer header. The connection lasts until that token expires. To keep it open, request a new token and send it on the connection before the old one expires:

{"type": "authenticate", "access_token": "<new access token>"}

The new token must come from the same client.

Errors​

HTTP statuserror_codeCause
401Permission_ErrorThe Authorization header is missing, or the token is invalid or expired. Request a new token
403Permission_ErrorThe token is valid, but your client lacks trading access (for a POST) or cannot access the account_number