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

# Authentication

> Authenticate every request with a Pav API key in the Authorization header.

Every `/v1` endpoint and the MCP server require a Pav API key, sent as a bearer
token.

```http theme={null}
Authorization: Bearer <your_api_key>
```

The **API Reference** playground accepts the same key.

## Create a key

1. Sign in at [app.pav.bio](https://app.pav.bio).
2. Open **Settings → Developer**.
3. Create a key. Choose a **personal** key (tied to your user) or an
   **organization** key (tied to your organization).
4. Copy the secret. It is shown once and cannot be retrieved later.

## Rotate and revoke

Create a new key, move your clients to it, then revoke the old key in
**Settings → Developer**. Revocation takes effect within a few minutes.

## Scopes

The API is read-only. Keys created without custom scopes work on every
endpoint. A key created with custom scopes must include `pav:pipeline:read`;
otherwise requests return `403 forbidden`.

## Authentication errors

| Status | `code`         | When                                                                                                  |
| ------ | -------------- | ----------------------------------------------------------------------------------------------------- |
| `401`  | `unauthorized` | Missing, malformed, unknown, revoked or expired key. The response carries `WWW-Authenticate: Bearer`. |
| `403`  | `forbidden`    | The key declares scopes but not `pav:pipeline:read`.                                                  |
| `503`  | `unavailable`  | Key verification is temporarily unavailable. Retry with backoff; your key is not rejected.            |

```json Example 401 response theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key",
    "request_id": "77c9734bd1ed47d8bf126ebcf58dc393"
  }
}
```

See [Rate limits and errors](/rate-limits) for the full error list.

<Warning>
  Treat a key like a password. Keep it out of source control, logs and
  client-side code. Read it from an environment variable or a secret store.
</Warning>