API keys

Key lifecycle#

Creating a key returns a raw ts_live_* secret once. The database stores only:

• SHA-256 hash;
• readable prefix;
• name and owner;
• creation, expiry, last-used, and revocation timestamps.

The raw secret cannot be recovered later.

Create and use a key#

Create keys from the authenticated API Keys page, then call the example endpoint:

curl https://app.example.com/api/v1/me \
  -H 'Authorization: Bearer ts_live_...'

Validation#

Bearer authentication rejects keys that are:

• missing or malformed;
• not found by hash;
• revoked;
• expired;
• detached from a valid user.

Successful validation updates the last-used timestamp.

Revocation#

Revocation keeps metadata for auditability but immediately rejects future bearer calls. The UI never shows the raw key again.

Extending scopes#

The current contract can be extended with a scope column and centralized authorization checks. Keep scope evaluation in the API-key domain rather than scattering string comparisons across routes.