API Authentication
TraceDB /v1 routes use bearer-token authentication.
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 for envelope details.