---
title: "Authenticate requests"
url: https://docs.truemarkets.co/developer-resources/authentication
description: "Sign a challenge with your API key to mint a token, then send it as a bearer token on every call."
---

Docs index: https://docs.truemarkets.co/llms.txt

# 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. A Trading API key returns an access token and a refresh token. A Gateway organization key returns an access token only.

The signing code is in TypeScript in each quickstart: [Trading API](https://docs.truemarkets.co/trading-api/quickstart#2-mint-a-token) and [Gateway](https://docs.truemarkets.co/gateway/quickstart#2-mint-an-organization-token).

**curl**

```bash
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…"
  }'
```

**Response** 200 (Trading API key)

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

**Response** 200 (organization key)

```json
{
  "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 you act for one of your users on Gateway, the request also carries `TM-On-Behalf-Of: <user_id>`. [Trade for a user](https://docs.truemarkets.co/gateway/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, on the Trading API you exchange 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 on Gateway you mint 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.

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

Next: [Errors](https://docs.truemarkets.co/developer-resources/errors)