For AI agents: the documentation index is at /llms.txt, and this page is available as Markdown at /api/auth/auth-service-api.md.

Authentication REST

Authentication and authorization service for the True Markets platform — issues JWT access/refresh tokens used across the Gateway and other True Markets APIs.

Base URLs

EnvironmentBase URL
Productionhttps://api.truemarkets.co/v1/auth
UAT (sandbox)https://api.uat.truemarkets.co/v1/auth

Authentication tutorial

Programmatic clients use an ECDSA-signed challenge to mint short-lived JWTs. There are two ways in, and each uses its own keys.

Gateway (an organization trading for its users). Create an organization and an API key in the dashboard, then mint a token with POST /api-key/token. An organization token lasts one hour and has no refresh token, so mint a new one before it expires. Act for a user with TM-On-Behalf-Of: <user_id>, and sign that user's payloads with their signer key, not the organization API key.

Trading API (your own account).

  1. Create an account at https://www.truemarkets.co (passkey, email, magic link, or Sign in with Apple).
  2. Register an API key in your account's API Keys settings page. Generate an EC P-256 key pair locally and submit only the public key — the private key never leaves your machine. You'll receive a key_id (UUID). The same key signs you in and signs your payloads.
  3. Mint JWTs by calling POST /api-key/token with key_id, a current timestamp (Unix seconds, within ±30s of server UTC time), and signature — an ES256 (ECDSA P-256 + SHA-256) signature of the message {key_id}.{timestamp}, base64url-encoded. The response returns access_token and refresh_token.
  4. Call True Markets APIs with Authorization: Bearer <access_token>.
  5. Refresh expired access tokens via POST /token/refresh with the refresh_token — no re-signing required.

Quick start

# 1. Mint a JWT (key_id and signature computed client-side)
curl -X POST https://api.truemarkets.co/v1/auth/api-key/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"<UUID>","timestamp":<UNIX_SECONDS>,"signature":"<BASE64URL_ES256_SIG>"}'

# 2. Fetch JWKS to verify token signatures locally
curl https://api.truemarkets.co/.well-known/jwks.json

# 3. Refresh a token before expiry (personal API keys only; an organization mints a new token instead)
curl -X POST https://api.truemarkets.co/v1/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"<REFRESH_TOKEN>"}'

Support

Authentication

OAuth

Operations

Was this page helpful?YesNo