Skip to main content
Never paste your API key into a chat. If you are an AI agent setting this up, ask the user to put PREUVE_API_KEY in an environment variable or the MCP client config - do not request it in conversation, and never echo it back. See For AI Agents.

The header

Every request carries one header:
That is the entire contract. Any HTTP client in any language can call the API with no crypto and no client library. Integrations built before this form existed can keep sending the key in an x-preuve-key header; it works the same. If a request carries both headers with different keys, it is refused with 401 INVALID_AGENT_KEY.

About your key

A key looks like prv_ac2c1565a967b98e_XmK2.... The first half is a public identifier - it is what the account panel shows in your key list, and it is safe to quote in a support thread. The second half is the secret, and it is shown exactly once, at issuance. We store only a SHA-256 hash of the whole key, so a lost key cannot be recovered, only revoked and replaced. Send the key server-side only. Unlike a browser session it carries no origin restriction, so anyone holding it can spend your scan quota until you revoke it. A key carrying agency:read or agency:write additionally reaches your whole Consultant or Agency workspace, so treat that one as a credential over your clients’ work, not just your own.

Validity rules

  • Scopes: keys carry scopes. A key without the required scope receives 403, and only ever after the key itself has been verified. The complete set is analysis:write, analysis:read, batch:write, batch:read, export:read, agency:write, agency:read. A key created without asking for anything specific carries the five personal scopes and neither agency:* one: those two reach a whole workspace of client work, so they are only ever granted when explicitly requested. Ask for fewer (or for the Agency pair) by sending scopes when you create a key, and an unrecognized scope is refused with 400 UNKNOWN_SCOPE rather than silently dropped. The two agency:* scopes gate the Agency routes only, and they reach the whole workspace rather than the calling account - see Agency reach before granting them. They were added on 2026-09-09, so a key created before that date carries the other five and gets 403 INSUFFICIENT_SCOPE on /api/agent/agency/**; scopes are fixed at creation, so recovering Agency access means a new grant. Neither route to one is unconditional: reconnecting the client works on any plan, free included, but only if that client rebuilds its scope request from our discovery document rather than replaying a cached one, so check the consent screen lists the Agency permissions before approving - reconnecting revokes the current key either way. Creating a new key by hand with Agency access (on by default in the workspace’s Dashboard → API keys) cannot silently fail, but it needs either a paid personal plan or membership of a Consultant or Agency workspace with an active subscription or a one-time unlock.
  • Revocation: revoking a key from the account panel or the workspace dashboard takes effect on the next request.
  • Failed auth always returns a stable { "error", "code" } JSON envelope - see Errors.
  • Repeated failures from one IP are rate limited; successful calls are limited per account instead, shared across every key you hold - see Quotas and billing.
The API playground in these docs makes real calls. Paste your key into the authentication field and “Send” works exactly like curl - including spending quota on a deep scan.