API tokens (planned)

Not yet available

First-class API tokens are a planned design, not a shipped feature. None of the endpoints or token formats on this page exist in the API today. To authenticate right now, use the session bearer token described in Authentication.

This page documents the proposed API-token programme so integrators can anticipate it. Everything below is roadmap.

Why

Today, programmatic access reuses the same session bearer token the apps use (minted by login, magic link or 2FA, stored server-side, sliding TTL). A first-class token programme would give integrations long-lived, scoped, revocable credentials that are independent of a user login session.

Proposed token format

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

• Environment prefix — sk_live_, sk_staging_ or sk_dev_.
• The secret is shown once at creation. Only a hash (SHA-256) would be stored server-side; the raw value could not be recovered.

Tokens would live in an api_tokens table recording the subject user, role, operator, scopes, master/impersonation flags, and expiry/revocation timestamps.

Proposed scopes

Phase 1 scoping would be role + operator: a token would carry a role and be bound to a specific operator, and would be evaluated against exactly the same identity model as a session — so every existing endpoint would honour it without change.

Proposed act-as delegation (master tokens only)

A master token would be able to act as another user or role by sending:

X-Act-As-User: <user_id>
X-Act-As-Role: <role>

This would be gated behind multiple controls: a master token, an explicit bypass header, an allow-list of debug IPs, and Cloudflare Access. Master tokens would be forced to a 90-day maximum expiry.

Proposed rotation & expiry

• Rotation — rolling a token keeps its row and identity but issues a new secret, so scopes and grants survive the roll.
• Expiry — tokens would carry an expires_at; master tokens would be capped at 90 days.
• Revocation — a revoked_at timestamp would immediately invalidate a token.

Proposed CRUD endpoints

Caution

These endpoints do not exist yet. Listed for reference only.

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 a token’s secret.
DELETE /api/admin/api-tokens/:id	Revoke a token.

What to do today

Use the session bearer token:

Authorization: Bearer <session-token>

When the token programme ships, sk_... tokens would be sent in the same Authorization: Bearer header and resolve to the same identity object, so code written against session auth today should carry over with minimal change.