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 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:
- verify the bearer key;
- check required scopes for the requested operation;
- bind the request to the authorized tenant, database, and branch;
- strip any inbound actor headers supplied by the caller;
- inject trusted actor headers derived from verified claims; and
- 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.