API tokens

API tokens (psql_live_…) authenticate the REST API and the MCP server. They are namespace-scoped — a token’s namespace match is enforced on every call.

Minting

Settings → API tokens → New token:

1. Pick a name (e.g. prod-orders-service).
2. The full secret is shown exactly once. Copy it now.
3. The token row from then on shows only psql_live_xxxx…yyyy so you can identify it without leaking the full value.

You can also mint via the agent: “create an API token called prod-orders-service” — the agent runs propose_create_token, asks for confirmation, then displays the secret in the chat exactly once.

Validation hot path

Every /v1/* and MCP request validates the bearer:

1. Check KV cache (token:<sha256(secret)>, 60s TTL) — hit returns the namespace + token id immediately.
2. Miss → look up in D1, then write the result back to KV.

That keeps token validation off the D1 hot path while still revoking in under a minute.

Spending controls

There is no per-token throughput limit and no per-token request count cap. Each database is its own Durable Object — tenants can’t crowd each other — and the namespace’s prepaid balance is the only spend control. A token runs as fast as your code calls it until the balance returns 402.

If you want to fence off a single key — a CI pipeline, an end-user session token, a sub-agent — mint it in a separate namespace whose balance is the maximum you’re willing to let that key spend. Keys in different namespaces cannot drain each other’s balance.

Revoking

Settings → API tokens → ⋮ → Revoke. KV is invalidated immediately; the longest possible window between revoke and full effect is the 60s KV TTL.

Hygiene

• Don’t reuse a token across services. Mint one per consumer so you can revoke surgically.
• Don’t commit tokens. Use environment variables / a secret manager.
• Rotate on suspected exposure. Mint a new one, switch consumers, revoke the old.