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):
| Item | Purpose |
|---|---|
| Token URL | Where you request access tokens |
| Client ID | Identifies your integration |
| Client secret | Proves 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.
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 status | error_code | Cause |
|---|---|---|
401 | Permission_Error | The Authorization header is missing, or the token is invalid or expired. Request a new token |
403 | Permission_Error | The token is valid, but your client lacks trading access (for a POST) or cannot access the account_number |