Project API keys

Use a project key over HTTPS:

Authorization: Bearer zaun_<64 hexadecimal characters>

New keys use the zaun_ prefix. Existing zaun_scan_ keys remain valid until revoked. Ingest keys, which send agent telemetry, use zaun_ingest_; see Ingest keys.

Create a key in API keys in the console. Select Run responses and list models for completion access (run:write). The secret is shown once. Store it in your application's secret store and load it at runtime. Keep it out of URLs, source control, logs, and browser code. The plaintext secret cannot be recovered after creation. Keys can expire or be revoked.

An account created by signup gets its first key automatically: a service key named Default key in the Default project, with scan:write, result:read and usage:read, and no expiry. It is shown once, on Home right after signup. If you lose it, revoke it and create another in API keys.

Each key belongs to one project and organization. The request cannot change that scope. Same-project keys with the appropriate permissions can access retained results and historical usage created by earlier keys, including after rotation. Other projects' results and usage are not accessible.

Scopes#

Ask for only the scopes your client needs. A read-only key cannot scan. Public health and documentation routes need no credential. Customer keys cannot administer organizations, projects, policy, or other keys.

Ingest keys#

An ingest key lets an agent's OpenTelemetry exporter send telemetry to one source of one project, such as your Claude Code fleet. It looks like this:

x-zaun-ingest-key: zaun_ingest_<64 hexadecimal characters>

Exporters take headers as name=value pairs, so use x-zaun-ingest-key, which needs no space. Authorization: Bearer zaun_ingest_... works too. The key decides the project and source; nothing in the telemetry can choose another.

An ingest key has the ingest:write scope and no other. It cannot scan, read results or usage, or administer anything; those requests return 403 forbidden. Treat it like an error-reporting key that ships in client configuration: anyone who reads it can send telemetry to that source and nothing more, and it is cheap to rotate.

To create one:

1. In Settings, open Telemetry and add a source for the group of agents, with the content they will send (prompts and replies, tool names and input, tool output, raw model API bodies).
2. In API keys, choose Create key, then Send telemetry, and pick the source.
3. Download the generated configuration while the key is on screen. The key is filled in; later downloads from Telemetry carry <ZAUN_INGEST_KEY> in its place.
4. Start a connectivity check in Telemetry, send its code through the agent, and open Health to see it arrive.

A source can have several active keys, so you can rotate without a gap: create a key for the same source, update the configuration, then revoke the old key. Refusals of a revoked or expired key are counted on its source's health report. An organization admin can turn a project's telemetry off in Telemetry; its ingest keys are then refused until it is turned back on. See limits and errors for the size limits and allowances.

Keys requested by an agent#

When an agent connected to Zaun's MCP server needs a key, it never receives one. It gets a claim link instead, bound to you, your organization and that agent, valid for ten minutes and usable once. Collect the key in one of two ways:

• Open the link in the console, signed in as yourself, and select Reveal key here. The key is created and shown once.

• Run the command the agent gives you in a terminal on your machine:

  shCopy

  npx -y @zaun/cli@0.1.0 claim <claim id or link>
  

  It prints a console link and an eight-character code. Open the link, type the code, and the key is saved to ~/.config/zaun/api-key, readable only by you. Only its prefix is printed. The console shows the address and program that are waiting for the key. Type the code only if you started the command yourself. Your agent should never give you this code; whoever ran the command that printed it receives the key.

Only an organization administrator can collect a claim. You can request five claims an hour. A key collected this way can run scans and nothing else: it carries scan:write only, so it cannot read results or usage. Create a key in API keys when you need those scopes. The key appears in API keys like any other service key; revoke it there if it was exposed or lost.

Agent access to violations#

An agent connected to Zaun's MCP server can read your project's violations without any key. It uses a short-lived token for you, limited to the scopes you approved and to your current role, and names the project in project_id on every call:

Each call checks your access again, so removing you from the project or the organization, or disabling your account, stops the agent on its next call. Every read is recorded with you, the agent's client, the project and the route. See Violations API. The token cannot scan, read results or usage, or stand in for a project key.

Rotate a key#

1. Create a replacement in the console with the required permissions and expiry.
2. Store the replacement and switch every client to it. Both keys work during this overlap, provided neither has expired or been revoked.
3. Verify a scan or permitted read with the replacement, then revoke the old key in API keys. The key ID, not the display prefix, identifies it.
4. Remove the old secret from client configuration. Existing project results and historical usage remain available to appropriately scoped replacements.

If a secret is exposed, revoke it immediately in API keys. Revocation and expiry reject subsequent authorization checks. Work already admitted can finish. Creating replacements does not increase the project or organization rate budget.

Authentication errors#

Rate limits and retries#

X-RateLimit-Remaining reports the organization's remaining request admissions for the current one-minute window. Token allowances are not reported. It appears on successful admissions and rate-limit denials. HTTP 429 rate_limited includes Retry-After, rounded up to whole seconds. Wait at least that long, then retry with backoff. Honor Retry-After on temporary availability errors too.

The API returns a generated scan_uuid for each scan and a request_uuid for each completion. Each HTTP request consumes admission allowance. Do not rotate credentials or create extra keys to bypass tenant limits. See limits and errors for budgets and retry outcomes.