API tokens

The API tokens resource manages the bearer credentials that authenticate every other call to this API — including future calls to this resource itself. Once a customer mints their first token via the dashboard, every subsequent token can be created and revoked through the API; you never need to log back into the dashboard for credential hygiene.

Two prefixes — don't confuse them

There are two prefix-shaped strings in play here, and they refer to different things:

  • The resource ID returned in JSON is tok_<32 hex chars> (Stripe-style ID prefix encoding the row's UUID). This is what you thread back into the URL for GET and DELETE.
  • The bearer credential returned once in the token field of the POST response is culprit_live_<43 base62 chars>. This is what you send in Authorization: Bearer <token> on every request.

One-time reveal, then HMAC-only

The raw token is shown in the POST response and never again. The database stores only an HMAC-pepper digest of the token bytes; we cannot recover or re-display it. To rotate, mint a new token, update your integration, and DELETE the old token's row.

Scope-escalation defense

A read_only token cannot mint new tokens — POST /v1/api_tokens is a mutating operation, and the auth gate rejects mutating calls from read-only credentials with 403 token_scope_insufficient. Mint read_write tokens from a read_write parent.

Notes

  • No PATCH. Tokens are immutable post-create — the bytes themselves are the credential.
  • Revoke is soft-delete: the row stays for forensic audit and the unique-prefix constraint prevents an attacker re-registering a revoked prefix.

Endpoints