API keys and the gateway

Every request to https://api.trazadb.com carries a project API key. The gateway checks it, checks its scope against the route, applies your project’s rate limit, and forwards the request to your project’s cell with an engine credential bound to your project’s tenant. The engine’s answer, status and headers come back unchanged, plus a Traza-Project header naming the project.

The key

Keys look like tzk_<project>_<40 characters>: 200 random bits after the prefix. A key is shown once, when it is created; Traza Cloud stores only its SHA-256. Revoking a key takes effect at once.

Send it as a bearer token:

curl -s https://api.trazadb.com/v1/whoami -H "Authorization: Bearer $TRAZA_API_KEY"

On the replay routes only, the gateway also accepts x-api-key: tzk_…, because that is the header the Anthropic SDK sends.

Scopes

Scope	Reaches	Use it for
ingest	POST /v1/spans, POST /v1/traces, POST /v1/fuses/check, GET /v1/whoami	Exporters, collectors, guard hooks
read	Every read a tenant-bound engine credential may make, plus POST /v1/fuses/check, POST /v1/mcp, and creating and calling replays	Dashboards, notebooks, MCP clients, replay harnesses
full	Everything read and ingest reach, plus annotations, dataset and experiment writes, run-fuse policy, trip and reset writes, and a run’s nudges (queueing and listing them)	Automation that changes things

Reads include search, traces, sessions, analytics, export, live tail, tapes, diffs, recall, usage, the ledger head and evidence packs: the routes in the HTTP reference that a bound ro credential can use, except a run’s nudges. GET /v1/runs/{run}/nudges takes a full key, like queueing one: an agent hears its nudges through its pre-call check, which any key can make (Steer).

Routes the gateway never forwards

These answer 404 at the gateway whatever the key: every path under /v1/admin/, /v1/backups/*, /v1/checkpoint, /v1/flush, /v1/verify, bare /v1/stats, every path starting /v1/metrics, /v1/ledger, /v1/ledger/verify and /v1/ledger/anchors, every method but GET under /v1/erasures, dataset version tombstones, and the dashboard at /. They operate on a whole cell, or remove what a project’s erasure receipt vouches for, rather than serving a project. Your project’s own evidence pack, usage and ledger head remain available, and deleting a project from the console erases its data with a receipt.

Rate limits

Each project has a token bucket sized by the organization’s plan; the per-plan rates and bursts are in the plan table. Past it, the gateway answers:

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{"error":"rate limited","retry_after_s":1}

OpenTelemetry exporters retry on 429 and honour Retry-After. A 429 that carries a quota object instead comes from the engine: the organization has reached its monthly spans, and ingest is paused until the period resets or the plan changes. Billing explains caps.

A 429 with "code":"auth_rate_limited" means requests from your address presented too many keys that could not be verified: mistyped, revoked or deleted keys, and checks that could not finish while the gateway was busy (503 with "code":"auth_busy" or "key_lookup_failed"). Keys the gateway has seen recently keep working. Other keys are not checked until Retry-After has passed. Fix the key rather than retrying in a loop.

Limits on a request

Request bodies are capped at 64 MiB (413 beyond). Requests time out after 60 seconds, counting until the whole response has been sent to your client: a response still being sent at 60 seconds is cut off (the connection is reset), so read responses as they arrive. Streams are the exception: live tail, export and streamed replays pass through as they are produced. A client that stops reading for 30 seconds while data is waiting is disconnected, so read streams as they arrive. A suspended organization can still read and export; only ingest is refused.