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

# Authentication

> API keys, headers, and security requirements for the hosted API.

The hosted PolyOrderbooks API (`api.polyorderbooks.com`) authenticates data requests with **API keys**. Keys are tied to your account plan and usage limits.

## Get an API key

1. [Create an account](https://polyorderbooks.com/signup).
2. **Verify your email** (required for password sign-ups).
3. Open the [dashboard](https://polyorderbooks.com/dashboard) → **API keys** → **Create key**.
4. Copy the secret when shown — you will not see it again.

Keys are prefixed with `pob_`. Store them in a secrets manager or environment variable — never in client-side code or public repositories.

## Send your key

**Recommended header:**

```http theme={null}
X-API-Key: pob_xxxxxxxxxxxxxxxx
```

**Alternative (same key format):**

```http theme={null}
Authorization: Bearer pob_xxxxxxxxxxxxxxxx
```

<Warning>
  **Dashboard JWTs are not API keys.** Session tokens from login/signup work only for dashboard routes (`/v1/auth/me`, `/v1/account/*`). They are rejected on `/v1/markets`, history endpoints, and `/v1/usage`.
</Warning>

## Example request

```bash theme={null}
curl -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets?search=bitcoin&limit=10"
```

## Protected routes

All `/v1` discovery and history endpoints require a valid API key. Send `X-API-Key: pob_…` or `Authorization: Bearer pob_…` on every data request.

## Security requirements

| Requirement      | Guidance                                                                       |
| ---------------- | ------------------------------------------------------------------------------ |
| **Transport**    | Always use HTTPS.                                                              |
| **Storage**      | Load keys from environment variables or a secrets manager.                     |
| **Rotation**     | Create a new key, migrate clients, then delete the old key from the dashboard. |
| **Environments** | Use separate keys per environment when possible.                               |
| **Scope**        | Each key inherits your account plan limits — see [Pricing](/pricing).          |

## Error responses

| Situation                            | HTTP  | Body                                                                            |
| ------------------------------------ | ----- | ------------------------------------------------------------------------------- |
| No key on a protected route          | `401` | `{"detail":"Authentication required."}`                                         |
| Invalid or revoked key               | `401` | `{"detail":"Invalid API key."}`                                                 |
| Unverified email (key creation only) | `403` | `{"error":"forbidden","message":"Verify your email before creating API keys…"}` |

Application validation errors use `error` + `message` — see [Error handling](/error-handling).

## Interactive playground

On endpoint **Try** panels in this documentation:

1. Select the **Production** server (`https://api.polyorderbooks.com`).
2. Add header `X-API-Key` with your `pob_…` secret.
3. Mintlify stores the key in your browser session only — it is not sent to our servers.

## Local development

When running the API locally with auth disabled, data routes are open without a key. Production behavior described here applies to the hosted API only.