Authenticate requests

Every authenticated call carries a token. You mint the token by signing a short challenge with your API key, and you replace it when it expires.

Mint a token

The challenge is the string {key_id}.{timestamp}, where timestamp is the current Unix time in seconds. It must be within 30 seconds of our clock. Sign it with ES256, concatenate r and s, base64url-encode the result, and post it with the key id and timestamp.

The response depends on the key. An API trader's key returns an access token and a refresh token. A Gateway client's organization key returns an access token only.

The signing code is in TypeScript in each quickstart: Trading API and Gateway.

Exchange a signature for a token

curl -s -X POST \
  https://api.truemarkets.co/v1/auth/api-key/token \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": "a1b2c3d4-…",
    "timestamp": 1790620800,
    "signature": "q3Zf0vN8kT2L…"
  }'

200 for an API trader's key

{
  "access_token": "eyJhbGciOiJFUzI1NiIs…",
  "refresh_token": "eyJhbGciOiJFUzI1NiIs…",
  "expires_in": "2026-09-28T18:11:27Z",
  "token_type": "Bearer"
}

200 for an organization key

{
  "access_token": "eyJhbGciOiJFUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": "2026-09-28T18:11:27Z"
}

Send the token

Put Authorization: Bearer <access_token> on every authenticated call. When a Gateway client acts for one of its users, the request also carries TM-On-Behalf-Of: <user_id>. Trade for a user covers that header.

Replace an expired token

An access token lasts an hour, and expires_in is the time it expires, not a number of seconds. Before then, an API trader exchanges the refresh token for a new pair without signing again. A refresh token lasts 30 days, and each refresh returns a new one, so keep the latest. An organization has no refresh token, so a Gateway client mints a new token from the key. Revoking a key stops its refresh tokens, but access tokens already minted keep working until they expire.

A 401 on any call means the token is missing, invalid or expired, or that an organization token called a user route without TM-On-Behalf-Of. Get a new token or add the header, then retry the request.

Refresh a token, API traders only

curl -s -X POST \
  https://api.truemarkets.co/v1/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d "{\"refresh_token\": \"$REFRESH_TOKEN\"}"

Next: Errors