> ## Documentation Index
> Fetch the complete documentation index at: https://docs.preuve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> One API key, one header. No signing, no bearer tokens, no sessions.

<Warning>
  **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](/for-ai-agents).
</Warning>

## The header

Every request carries one header:

| Header | Value |
| - | - |
| `x-preuve-key` | Your API key (`prv_...`), sent as-is |

```bash theme={null}
curl https://preuve.ai/api/agent/analyses \
  -H "x-preuve-key: $PREUVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"clientRunId":"my-run-001","scanType":"starter","idea":"..."}'
```

That is the entire contract. Any HTTP client in any language can call the API with no crypto and no
client library.

## 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](/for-ai-agents#on-an-agency-account-the-reach-is-wider)
  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 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](https://preuve.ai/app?settings=apiKeys)
  takes effect on the next request.
* **Failed auth** always returns a stable `{ "error", "code" }` JSON envelope - see [Errors](/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](/quotas-and-billing).

<Note>
  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.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.