Authentication

API token

Requests are authenticated with a bearer token supplied in a single header:

Authorization: Bearer <token>

The token is the key secret displayed once at key creation. No clock synchronisation, nonce or request signature is involved. A lost token cannot be recovered; the key must be rotated instead.

Tokens must be transmitted over TLS and handled as any other bearer credential: excluded from version control and from query strings, and scoped to the narrowest set of capabilities the integration requires.

Session tokens

Session tokens exist for clients that should not hold the key secret itself — an MCP client operated by a third-party agent, or the documentation console, which executes in a browser. A session is obtained by exchanging an authenticated request for a short-lived, optionally narrowed credential:

POST /v1/auth/session
{ "audience": "mcp", "ttl_seconds": 3600, "capabilities": ["geo.forward"] }

• capabilities may only narrow the set already held by the key. A session cannot extend a key's authorization.
• Revoking a key invalidates every live session issued from it immediately. Sessions are validated against the key on every call, not only at issue time.
• Entitlement changes also invalidate live sessions, so that a session issued before a capability was cancelled does not outlive the cancellation.
• A session cannot issue a further session.

Key management

• Rotation. rotate issues a new secret and keeps the previous key valid for a grace window, so rotation does not require a coordinated cutover. Revoke the previous key once the deployment has been updated.
• Scoping. A key may be restricted to a subset of the account's capabilities. The effective set is the intersection of the account subscription and the key's scopes, which limits the exposure of a disclosed key without any server-side change.
• Separation. Issue one key per consuming system, so that revoking one does not interrupt the others.

Errors

Code	Status	Meaning
TOKEN_MISSING	401	No credential was supplied.
TOKEN_INVALID	401	The token is unknown, or belongs to a revoked key.
KEY_UNKNOWN	401	No key exists with the given identifier.
KEY_REVOKED	401	The key has been revoked.
SESSION_EXPIRED	401	The session token has expired or was not issued by this platform.