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

# Authentication

> API key management, test vs. live environments, and security best practices.

## API keys

Every request to PDFBase requires an API key passed in the `Authorization` header.

```bash theme={null}
Authorization: Bearer pk_live_abc123def456
```

### Key types

| Prefix     | Environment | Behavior                                                 |
| ---------- | ----------- | -------------------------------------------------------- |
| `pk_test_` | Test        | Watermarked PDFs, no billing, rate limited to 10 req/min |
| `pk_live_` | Live        | Production PDFs, metered billing, full rate limits       |

Test keys generate fully functional PDFs with a diagonal "PDFBASE TEST" watermark. Use them for development and CI pipelines.

### Key management

Create, rotate, and revoke keys from the [API Keys](https://app.pdfbase.dev/api-keys) page in your dashboard.

* Each account can have up to **5 live keys** and **5 test keys** active simultaneously.
* Keys can be scoped to specific operations (e.g., create-only, read-only).
* Rotating a key gives you a 24-hour grace period where both old and new keys work.

### Key scopes

Restrict what a key can do by assigning scopes at creation time.

| Scope             | Permissions                              |
| ----------------- | ---------------------------------------- |
| `pdfs:create`     | Create PDFs (HTML, URL, template render) |
| `pdfs:read`       | Retrieve and list PDFs                   |
| `templates:write` | Create, update, delete templates         |
| `templates:read`  | Retrieve and list templates              |
| `batches:write`   | Create batch jobs                        |
| `batches:read`    | Retrieve batch status                    |
| `*`               | Full access (default)                    |

```bash theme={null}
# A key scoped to only create PDFs
curl -X POST https://api.pdfbase.dev/v1/pdfs \
  -H "Authorization: Bearer pk_live_SCOPED_CREATE_ONLY" \
  -d '{"html": "<h1>Works</h1>"}'

# Same key trying to list templates — 403
curl https://api.pdfbase.dev/v1/templates \
  -H "Authorization: Bearer pk_live_SCOPED_CREATE_ONLY"
# => 403 Forbidden: key missing scope 'templates:read'
```

## Security

<Warning>
  Never expose API keys in client-side code, public repositories, or browser requests. PDFBase is a server-side API.
</Warning>

### Best practices

1. **Use environment variables.** Store keys in `PDFBASE_API_KEY`, never hardcode them.
2. **Use test keys in CI.** Your test suite should never touch live keys.
3. **Scope keys narrowly.** A service that only generates PDFs doesn't need `templates:write`.
4. **Rotate quarterly.** Use the 24-hour grace period to update all services without downtime.
5. **Monitor usage.** The dashboard shows per-key usage — a spike on a key you don't recognize means it's leaked.

### IP allowlisting

For additional security, restrict API keys to specific IP addresses or CIDR ranges from the dashboard. Requests from non-allowed IPs return `403`.

```json theme={null}
{
  "error": {
    "type": "forbidden",
    "code": "ip_not_allowed",
    "message": "Request IP 203.0.113.50 is not in the allowlist for this key.",
    "param": null
  }
}
```