Authentication

Every API request must carry a valid API key. Keys are account-scoped bearer tokens issued through the Puck console (Settings → API Keys). There is no OAuth flow; the key is the credential.

Key format

All keys follow the pattern pck_live_<random>. Test-mode keys (issued in sandbox accounts) use pck_test_<random>. The prefix is validated server-side; sending a key with the wrong prefix returns 401 Unauthorized rather than a scope error.

Header format

Authorization: Bearer pck_live_…

Do not base64-encode the key; the Bearer scheme sends it as-is. Sending the key in a query string (?api_key=…) is not supported.

Scopes

Every key is issued with one or more named scopes. A request that requires a scope the key does not have returns 403 Forbidden with { "error": "insufficient_scope" }.

Scope	What it allows
investigations:trigger	Submit new investigations; cancel running ones
investigations:read	List and fetch investigation status and results
webhooks:manage	Create, update, delete, and test webhook subscriptions
graph:read	Query the blast-radius graph
agents:read	List agents and read per-agent config
findings:read	List findings
findings:dismiss	Dismiss a finding
reports:read	Fetch investigation reports
curiosity:read	List the curiosity queue
curiosity:write	Create, update, and delete curiosity items

Scopes are additive. A key with both investigations:trigger and investigations:read can do both. A key with no scopes is valid but useless — every call will return 403.

When you create a key, choose the minimum set of scopes your integration needs. Webhook consumers that only read results should not hold investigations:trigger.

Issuing a key

1. In the console, go to Settings → API Keys.
2. Click New key.
3. Give it a name (e.g. ci-integration) and select scopes.
4. Copy the key immediately — it is shown exactly once.

The console stores a salted hash; there is no way to recover a lost key. If you lose it, revoke it and issue a new one.

Rotating a key

Key rotation is zero-downtime:

1. Issue a second key with the same scopes.
2. Deploy the new key to all consumers.
3. Verify consumers are using the new key (no 401 errors in logs).
4. Revoke the old key from the console.

There is no forced expiry, but rotating keys on a schedule (every 90 days) is recommended. You can set a reminder in the console.

Common questions

Can I use the same key for multiple integrations? Technically yes, but you lose audit granularity. Separate keys let you see which system triggered which investigation and revoke per-integration without impacting others.

What does the 401 vs 403 distinction mean? 401 Unauthorized means the key is missing, malformed, or revoked — the server cannot identify who is calling. 403 Forbidden means the server knows who you are but that key does not have the required scope.

Are keys scoped to specific agents? No. Keys are account-scoped. Agent-to-brain authentication uses mTLS with a pinned certificate, which is separate from the console/API key system.