> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trace-db.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trace-db.com/_mcp/server.

# API Authentication

TraceDB `/v1` routes use bearer-token authentication.

```http
Authorization: Bearer <token>
```

Local development commonly uses a static development token such as `dev-token`.
Hosted Alpha uses scoped API keys issued by the hosted control plane.

## Hosted Scope

A hosted API key is scoped to the claims required to authorize a request:

* tenant;
* database;
* branch;
* token identity;
* policy epoch; and
* allowed scopes such as `records:write`.

The gateway verifies these claims before forwarding protected requests to the
engine.

## Actor Headers

External callers must not rely on caller-supplied `x-tracedb-*` actor headers.
For protected hosted routes, the gateway strips inbound actor metadata, injects
trusted headers derived from verified claims, and forwards the private engine
token after authorization.

This makes bearer-key verification the authority for hosted identity. A request
with a valid API key and spoofed actor headers should still execute as the
verified key's tenant, database, branch, and scopes.

## Secrets

Never commit or publish API keys, Railway tokens, Fern tokens, registry tokens,
AWS credentials, Cloudflare tokens, OTPs, or invite links. Store provider and
smoke credentials in local-only or provider secret stores, and redact values in
validation receipts.

## Failure Modes

* Missing, malformed, or invalid bearer tokens fail closed.
* Valid tokens without the required scope fail authorization.
* Hosted routes that require database or branch context fail when that context
  cannot be derived from verified claims or supported routing metadata.

Error responses use the standard TraceDB JSON envelope unless the failing route
is GraphQL. See [Errors](/api/errors) for envelope details.