Authentication

1.1 Overview

All API calls (except the login endpoint itself) require a short-lived JWT access token supplied as a Bearer token in the Authorization header. Access tokens expire quickly; use the refresh endpoint to obtain a new one without re-entering credentials.

The same access token can be passed to the WebSocket endpoint as the token query parameter.

1.2 Endpoints

POST /auth/login

Authenticate with username and password.

Request body (JSON):

{
  "username": "trader1",
  "password": "secret"
}

Response 200 (JSON):

{
  "access_token": "<jwt>",
  "refresh_token": "<opaque>",
  "access_expires_at": 1716180000,
  "permission_tier": 2
}

Field	Type	Description
access_token	string	JWT for API requests; include as Authorization: Bearer <access_token>
refresh_token	string	Opaque token; use with /auth/refresh
access_expires_at	int	Unix epoch seconds when the access token expires
permission_tier	int	1=Monitor, 2=Trader, 3=Power, 4=Admin

POST /auth/refresh

Obtain a new access token using a refresh token.

Request body (JSON):

{ "refresh_token": "<opaque>" }

Response 200 (JSON):

{
  "access_token": "<new_jwt>",
  "access_expires_at": 1716183600
}

POST /auth/logout

Invalidate the current session. The access token is added to the JWT blocklist; the refresh token is revoked.

Headers: Authorization: Bearer <access_token>

Response: 204 No Content

1.3 Error responses

All endpoints return standard HTTP status codes. Error bodies follow:

{ "error": "human-readable message", "code": "machine_code" }

Common codes:

HTTP Status	Meaning
400	Bad request / validation error
401	Missing or invalid token
403	Insufficient permission tier
404	Resource not found
409	Conflict (e.g. duplicate idempotency key)
422	Unprocessable entity (business rule violation)
429	Rate limit exceeded
500	Internal server error

1.4 Rate limiting

The API enforces per-IP and per-user rate limits on write endpoints. When a limit is exceeded, the response is 429 Too Many Requests with a Retry-After header in seconds.

---