Authentication

The External API has two credentials. Using the right one for the right caller is the whole security model.

API keys (your backend)

Your API key looks like ath_live_…. It authenticates every server-to-server call — managing your roster, minting sessions and reading calls — as a bearer token:

Authorization: Bearer ath_live_xxxxxxxxxxxxxxxxxxxxxxxx

• You receive it from Athos, shown once at creation. Store it as a backend secret (ATHOS_API_KEY). It is never retrievable again — if you lose it, rotate.
• It is the tenant boundary: it scopes every read to your data.
• Never expose it to a browser. The six API-key endpoints are not CORS-enabled, so a browser blocks their responses (see CORS).

Rotation

Athos supports zero-downtime rotation with multiple keys: a tenant can hold up to 5 active keys at once, so the old and the new key can serve traffic side by side while you deploy. To mint a sixth, revoke one first.

A revoked key immediately returns 401 API_KEY_REVOKED.

Session tokens (the browser SDK)

A session token is a short-lived JWT your backend mints with POST /v1/session. It authenticates exactly one action: the SDK redeeming a live roleplay call.

• Lifetime: ~5 minutes. Mint it when the rep clicks "start", not on page load.
• Single-use: it is consumed the moment the SDK connects. A second redemption returns 401 TOKEN_ALREADY_USED.
• Scope: it is minted for one registered agent — you pass that rep's platformAgentId or Athos agentId, and an unregistered id answers 404 AGENT_NOT_FOUND. The token cannot read calls, usage, or anything else — only start a session for that rep.

Because it's short-lived and single-use, there's no refresh flow and nothing to revoke. See minting tokens for the request shape.

  API key  ──▶  POST /v1/session  ──▶  session token (JWT, ~5 min, single-use)
   (backend, secret)                     (browser, scoped to one rep, one call)

CORS

Only the SDK's redeem endpoint (POST /v1/roleplay/session) accepts cross-origin browser requests. The six API-key endpoints reject them — if you call one from a browser it fails CORS, and that's intentional: put those calls behind your own backend. The per-endpoint table is on the API reference.

The support flow

Every response from a v1 endpoint carries an X-Athos-Request-Id header (e.g. req_2f8c1e94-…). Every webhook delivery carries a requestId in its body. When something looks wrong:

1. Grab the X-Athos-Request-Id (API) or the webhook requestId.
2. Send it to your Athos contact.

We can trace the exact request from that id. It's the fastest path to a resolution — always include it.

Error responses

Authentication failures use the standard error envelope:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key",
    "requestId": "req_2f8c1e94-3b6a-4d20-9a7e-1c5f0b8e2d44"
  }
}

Branch on code, never on message. The full list is in the error reference.