Skip to content

authentication.mdx

Latest commit

 

History

History
87 lines (65 loc) · 3.54 KB

authentication.mdx

File metadata and controls

87 lines (65 loc) · 3.54 KB
Raw
title Authentication
description Bearer credentials for the Tumban API — API keys for server use, session tokens for dashboard sessions.
icon key

{/* sources: src/auth, src/api/routes_auth.py */}

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.

Endpoint Required auth
PATCH /org/settings Dashboard session, admin role
POST /org/webhook-secret/rotate Dashboard session, admin role
POST /org/api-keys Dashboard session (any role)
GET /org/api-keys Dashboard 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

Status Meaning
401 Missing Authorization header, malformed Bearer prefix, or invalid/revoked credential.
403 Token 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.