API tokens (planned)

Not yet available

A first-class API-token programme is planned but not implemented. Nothing on this page exists yet - no tokens can be issued and none of the endpoints below are live. Everything here is roadmap.

Today, authenticate with a session bearer token - see Authentication.

Why API tokens

Session bearer tokens are minted by logging in and expire on a sliding TTL, which suits interactive use but not long-lived server-to-server integrations. The planned sk_ tokens are designed for exactly that: a stable, revocable credential you create once and store in your backend.

Proposed token format

Tokens will be structured strings:

sk_<env>_<prefix>_<secret>

• env - live, staging or dev, so a key is unmistakably tied to an environment.
• prefix - a short public identifier used to look the token up.
• secret - the high-entropy secret, shown once at creation. Only a SHA-256 hash is stored server-side; the raw value cannot be recovered.

A token would present the same identity to the API as a session, so existing Authorization: Bearer <token> handling stays unchanged - the API would simply recognise the sk_ prefix.

Proposed scopes

Phase one scoping is role + operator: a token carries a role and is bound to a specific operator, and is authorised exactly as that role would be, on that operator’s venues. Finer-grained per-endpoint scopes are a later phase.

A privileged master token type is envisaged for platform integrations, with an optional act-as capability (X-Act-As-User / X-Act-As-Role) gated behind additional controls. Master tokens would carry a forced expiry.

Rotation & expiry

• Rotation - rolling a token keeps its row and identity but issues a new secret, so you can rotate without re-provisioning.
• Expiry - tokens may carry an expires_at; master tokens are planned to be forced to a 90-day maximum.
• Revocation - a token can be revoked immediately, invalidating it without affecting others.

Proposed endpoints

All of these are design-only and not yet built:

Method	Path	Purpose
POST	/api/admin/api-tokens	Create a token (secret returned once)
GET	/api/admin/api-tokens	List tokens (metadata only)
POST	/api/admin/api-tokens/:id/roll	Rotate - keep the row, issue a new secret
DELETE	/api/admin/api-tokens/:id	Revoke a token

Until this ships, integrate with session bearer auth as described in Authentication.