> 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.

# Managed Routing

Requests targeting hosted/private engine endpoints that access tenant resources
must be authorized by the gateway before reaching the engine. Public health and
other explicitly public endpoints described in [Hosted Alpha](/start/hosted-alpha)
are exempt. For protected requests, the gateway is responsible for verifying
bearer keys, stripping client-supplied actor headers, injecting trusted actor
headers, and forwarding the private engine token.

## Caller Inputs

Hosted callers authenticate with a scoped bearer key. Database and branch
routing may be provided through SDK configuration, request options, or explicit
hosted-control-plane context, depending on the client surface.

Client-supplied `x-tracedb-*` actor headers are not trusted. A client cannot
become another tenant, database, branch, or token identity by sending those
headers directly.

## Gateway Responsibilities

For protected hosted routes, the gateway must:

1. verify the bearer key;
2. check required scopes for the requested operation;
3. bind the request to the authorized tenant, database, and branch;
4. strip any inbound actor headers supplied by the caller;
5. inject trusted actor headers derived from verified claims; and
6. forward the private engine token only after authorization succeeds.

The engine should observe actor metadata from the gateway, not from the
external caller. Gateway behavior must be proven against `api.trace-db.com`
before Hosted Alpha is treated as complete.

## Public Runtime Boundary

Managed routing is hosted-control-plane behavior. Self-hosted runtime users can
run the public HTTP `/v1` API without adopting TraceDB Cloud account, invite,
quota, or provider workflows.