---
title: "Authentication REST"
url: https://docs.truemarkets.co/api/auth/auth-service-api
description: "Exchange an API key signature for a token, and refresh it."
---

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

# 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).**

1. **Create an account** at [https://www.truemarkets.co](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

```bash
# 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

- 📧 [support@truemarkets.co](mailto:support@truemarkets.co)

## Authentication

- [Refresh access token](https://docs.truemarkets.co/api/auth/refresh-token): `POST /token/refresh`
- [Exchange API key for tokens](https://docs.truemarkets.co/api/auth/exchange-api-key-token): `POST /api-key/token`

## OAuth

- [Start an authorization request](https://docs.truemarkets.co/api/auth/oauth-authorize): `GET /oauth/authorize`
- [Record a consent decision](https://docs.truemarkets.co/api/auth/oauth-consent): `POST /oauth/consent`
- [Exchange a grant for tokens](https://docs.truemarkets.co/api/auth/oauth-token): `POST /oauth/token`
- [OAuth resource token key set](https://docs.truemarkets.co/api/auth/oauth-resource-jwks): `GET /.well-known/oauth-resource-jwks.json`
- [Describe an authorization request](https://docs.truemarkets.co/api/auth/oauth-authorize-details): `GET /oauth/authorize/details`
- [List connected apps](https://docs.truemarkets.co/api/auth/list-o-auth-consents): `GET /oauth/consents`
- [Revoke a connected app](https://docs.truemarkets.co/api/auth/revoke-o-auth-consent): `DELETE /oauth/consents/{client_id}`
- [Register an OAuth client](https://docs.truemarkets.co/api/auth/register-o-auth-client): `POST /oauth/register`
- [Authorization server metadata](https://docs.truemarkets.co/api/auth/oauth-authorization-server-metadata): `GET /.well-known/oauth-authorization-server`

## Operations

- [Refresh access token](https://docs.truemarkets.co/api/auth/refresh-token): `POST /token/refresh`
- [Exchange API key for tokens](https://docs.truemarkets.co/api/auth/exchange-api-key-token): `POST /api-key/token`
- [Start an authorization request](https://docs.truemarkets.co/api/auth/oauth-authorize): `GET /oauth/authorize`
- [Record a consent decision](https://docs.truemarkets.co/api/auth/oauth-consent): `POST /oauth/consent`
- [Exchange a grant for tokens](https://docs.truemarkets.co/api/auth/oauth-token): `POST /oauth/token`
- [OAuth resource token key set](https://docs.truemarkets.co/api/auth/oauth-resource-jwks): `GET /.well-known/oauth-resource-jwks.json`
- [Describe an authorization request](https://docs.truemarkets.co/api/auth/oauth-authorize-details): `GET /oauth/authorize/details`
- [List connected apps](https://docs.truemarkets.co/api/auth/list-o-auth-consents): `GET /oauth/consents`
- [Revoke a connected app](https://docs.truemarkets.co/api/auth/revoke-o-auth-consent): `DELETE /oauth/consents/{client_id}`
- [Register an OAuth client](https://docs.truemarkets.co/api/auth/register-o-auth-client): `POST /oauth/register`
- [Authorization server metadata](https://docs.truemarkets.co/api/auth/oauth-authorization-server-metadata): `GET /.well-known/oauth-authorization-server`