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
| Environment | Base URL |
|---|---|
| Production | https://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).
- Create an account at https://www.truemarkets.co (passkey, email, magic link, or Sign in with Apple).
- 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. - Mint JWTs by calling
POST /api-key/tokenwithkey_id, a currenttimestamp(Unix seconds, within ±30s of server UTC time), andsignature— an ES256 (ECDSA P-256 + SHA-256) signature of the message{key_id}.{timestamp}, base64url-encoded. The response returnsaccess_tokenandrefresh_token. - Call True Markets APIs with
Authorization: Bearer <access_token>. - Refresh expired access tokens via
POST /token/refreshwith therefresh_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
- Refresh access token:
POST /token/refresh - Exchange API key for tokens:
POST /api-key/token
OAuth
- Start an authorization request:
GET /oauth/authorize - Record a consent decision:
POST /oauth/consent - Exchange a grant for tokens:
POST /oauth/token - OAuth resource token key set:
GET /.well-known/oauth-resource-jwks.json - Describe an authorization request:
GET /oauth/authorize/details - List connected apps:
GET /oauth/consents - Revoke a connected app:
DELETE /oauth/consents/{client_id} - Register an OAuth client:
POST /oauth/register - Authorization server metadata:
GET /.well-known/oauth-authorization-server
Operations
- Refresh access token:
POST /token/refresh - Exchange API key for tokens:
POST /api-key/token - Start an authorization request:
GET /oauth/authorize - Record a consent decision:
POST /oauth/consent - Exchange a grant for tokens:
POST /oauth/token - OAuth resource token key set:
GET /.well-known/oauth-resource-jwks.json - Describe an authorization request:
GET /oauth/authorize/details - List connected apps:
GET /oauth/consents - Revoke a connected app:
DELETE /oauth/consents/{client_id} - Register an OAuth client:
POST /oauth/register - Authorization server metadata:
GET /.well-known/oauth-authorization-server
- Need help? Ask us on Discord, or email [email protected].
- See what changed in the changelog