# Auth Service API

Authentication and authorization service for the True Markets platform — issues JWT access/refresh tokens used across the Gateway, DeFi, 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.

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).
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** (Gateway, DeFi) 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
curl -X POST https://api.truemarkets.co/v1/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"<REFRESH_TOKEN>"}'
```

## Support
- 💬 [Discord](https://discord.gg/SC92xRUZqw) — community and integration help
- 📧 [support@truemarkets.co](mailto:support@truemarkets.co) — account, network, onboarding


Version: 1.0.0

## Servers

Production
```
https://api.truemarkets.co/v1/auth
```

UAT (sandbox)
```
https://api.uat.truemarkets.co/v1/auth
```

## Download OpenAPI description

[Auth Service API](https://docs.truemarkets.co/_bundle/apis/auth/openapi.yaml)

## Health

### Health check

 - [GET /health](https://docs.truemarkets.co/apis/auth/openapi/health/gethealth.md): Returns the health status of the auth service

## JWKS

### Get JSON Web Key Set

 - [GET /.well-known/jwks.json](https://docs.truemarkets.co/apis/auth/openapi/jwks/getjwks.md): Returns the public keys used to verify JWT tokens

## Token

### Refresh access token

 - [POST /token/refresh](https://docs.truemarkets.co/apis/auth/openapi/token/refreshtoken.md): Exchange a valid refresh token for a new access/refresh token pair

## API Key Authentication

### Exchange API key for tokens

 - [POST /api-key/token](https://docs.truemarkets.co/apis/auth/openapi/api-key-authentication/exchangeapikeytoken.md): Verify an ECDSA P-256 signature and issue JWT tokens. The client signs
the message {key_id}.{unix_timestamp} with their private key using ES256.
The timestamp must be within ±30 seconds of the server time.