Authentication

To create tenants and keys, see Tenants and keys. To set up identity tokens, see Identity tokens. To add dashboard sign-in through your IdP, see Dashboard SSO.

Data plane

Every request on port 8080 except GET /health carries a credential, an API key or an identity token, in one of two headers:

Anthropic clients send x-api-key by default; set ANTHROPIC_API_KEY to a gateway key. The gateway strips both headers before forwarding to a model backend. The MCP gateway (/mcp/{server}) and /v1/verdicts accept the same credentials.

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer $OBLETH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "example-model", "messages": [{"role": "user", "content": "Hello"}]}'

When OBLETH_JWT_ISSUERS is set, a credential that starts with eyJ, has exactly two dots and is at most 8 KiB is verified as an identity token. Anything else is looked up as an API key.

Failure responses

Errors use {"error": {"message": "…", "type": "obleth_gateway_error"}}. /v1/messages and /v1/messages/count_tokens return the same statuses in the Anthropic error envelope, with missing api key when no credential is sent. A Redis error during the lookup returns 503, not 401, so a Redis outage does not look like a revoked key to clients.

API keys

The pepper is OBLETH_API_KEY_PEPPER (Helm obleth.apiKeyPepper). With it set, a copy of the database alone cannot confirm guessed keys. Adding, changing or removing it invalidates every secret key issued before, and a restored backup authenticates only on a gateway with the same pepper.

Each key has a kind:

Both kinds carry the same tenant, weight, max_in_flight, budget, model list and usage. What each key action does to authentication:

The dashboard server holds one reserved key of its own, in a reserved tenant that is hidden from key lists and cannot be edited through the API. Every endpoint is in the Management API reference.

Identity tokens (JWT)

With OBLETH_JWT_ISSUERS set, the data plane accepts short-lived JWT access tokens from the issuers it lists. A verified token maps to an identity key, an api_keys row with kind = 'identity' and key_hash = jwt: + SHA-256 of issuer, a zero byte, and subject. From then on the request is handled like one with a secret key.

OBLETH_JWT_ISSUERS is a JSON array read once at start. A parse error, a duplicate issuer, a disallowed algorithm, or a failed discovery fetch stops the gateway from starting. Each entry takes:

Signing keys are cached per issuer and refreshed every 15 minutes. A token with an unknown kid triggers a refetch, at most one per issuer per minute. The discovery and JWKS URLs pass the same outbound-URL policy as model upstreams. Outcomes are counted in obleth_jwt_verify_total{result} and obleth_jwks_refresh_total{issuer_index,result} (Prometheus metrics).

Management API

Every request on port 9180 carries the admin token:

curl http://localhost:9180/api/v1/tenants \
  -H "Authorization: Bearer $OBLETH_ADMIN_TOKEN"

The whole header must equal Bearer <OBLETH_ADMIN_TOKEN>, compared in constant time; x-api-key is not accepted. A missing or wrong token returns 401 with {"error": "unauthorized"}. The token has no default: the gateway does not start without it. It grants full access, with no per-user roles. GET /api/v1/health, GET /api/v1/version and GET /api/v1/openapi.json need no token. Keep port 9180 private (Security).

Dashboard

The dashboard has its own sign-in; browsers never see the admin token. Its server calls the Management API with OBLETH_ADMIN_TOKEN.

A new SSO user starts as a pending user until an admin activates them on the Users page. The seed never re-promotes an existing account with the same email. No admin can demote or deactivate themselves or the last active admin.