> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tumban.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Bearer credentials for the Tumban API — API keys for server use, session tokens for dashboard sessions.

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](/api/keys/create). 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

```http theme={null}
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`](/api/org/update-settings)               | Dashboard session, **admin role**                                                                   |
| [`POST /org/webhook-secret/rotate`](/api/webhook-secret/rotate) | Dashboard session, **admin role**                                                                   |
| [`POST /org/api-keys`](/api/keys/create)                        | Dashboard session (any role)                                                                        |
| [`GET /org/api-keys`](/api/keys/list)                           | Dashboard session (any role)                                                                        |
| [`DELETE /org/api-keys/{key_id}`](/api/keys/revoke)             | Dashboard session (any role; see [Revoke API key](/api/keys/revoke) 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](/api/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](/api/keys/create) and deploy it to your servers.
2. Once traffic has cut over (watch `last_used_at` on the old key via
   [List API keys](/api/keys/list)), [revoke the old
   key](/api/keys/revoke).

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](/api/errors) for the full error envelope.