Skip to main content
All Tumban API requests require an Authorization: Bearer <token> header. Tumban accepts two token kinds:
  • API keys (sk_…) — long-lived secrets you create in the dashboard or via Create API key. Use these for server-to-server integration.
  • Session tokens — short-lived credentials issued to a signed-in dashboard user. Used by the Tumban dashboard. You generally do not handle these directly.

​
Header format

Authorization: Bearer sk_<64-hex-string>
Any token starting with sk_ is treated as an API key; anything else is treated as a session token.

​
What API keys can do

API keys are scoped to your organization and can call every endpoint in this reference except the five management endpoints below. These require a dashboard session because they mutate authentication or organization-wide configuration.
EndpointRequired auth
PATCH /org/settingsDashboard session, admin role
POST /org/webhook-secret/rotateDashboard session, admin role
POST /org/api-keysDashboard session (any role)
GET /org/api-keysDashboard session (any role)
DELETE /org/api-keys/{key_id}Dashboard session (any role; see Revoke API key for role-aware ownership rules)
API keys hitting any of these endpoints get 403 — credential management is intentionally locked out of sk_… auth so a leaked key cannot mint, list, or revoke other keys. See Errors → common detail strings for the exact detail text to match on. Each request looks up the key by SHA-256 hash, scopes the request to the key’s organization, and updates the key’s last_used_at timestamp. Revoked keys return 401 Invalid or revoked API key.

​
Rotating an API key

Tumban does not expire API keys automatically. To rotate:
  1. Create a new key and deploy it to your servers.
  2. Once traffic has cut over (watch last_used_at on the old key via List API keys), revoke the old key.
There is no overlap window beyond the time it takes you to deploy — both keys remain valid until the old one is revoked.

​
Storage

Tumban only stores the SHA-256 hash of an API key. The raw sk_… value is returned exactly once at creation time. If you lose it, revoke the key and create a new one.

​
Organization identifier

Every authenticated request resolves to exactly one org_id. Tumban treats it as an opaque, case-sensitive string — do not regex-match it against a hex or numeric alphabet. The leading org_ prefix is the only guaranteed part of the shape. Examples (org_2abc...) in this reference are illustrative; the body is alphanumeric and may include mixed case.

​
Errors

StatusMeaning
401Missing Authorization header, malformed Bearer prefix, or invalid/revoked credential.
403Token decodes but the active organization context is missing (session tokens only), or API-key auth was used on one of the five endpoints that require a dashboard session (see table above), or the role is insufficient on an admin-only endpoint.
See Errors for the full error envelope.