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

# Authentication

> API keys, the Bearer header, test keys, rotation, and using the playground.

Every endpoint except [`GET /v1/health`](https://docs.pinakelai.com/api-reference/account/health) and `GET /v1/openapi.json` needs an API key, sent as a Bearer token in the `Authorization` header:

```bash theme={null}
curl "https://api.pinakelai.com/v1/usage" \
  -H "Authorization: Bearer pk_live_..."
```

The scheme name is case-insensitive (`Bearer`, `bearer`). If a request carries both `Authorization` and the old `X-API-Key` header, the `Authorization` header is used.

## Keys

A key is `pk_live_` or `pk_test_` followed by 43 URL-safe characters.

| Key | Data | Limits | Billed |
| - | - | - | - |
| `pk_live_…` | All registers your agreement covers | Your agreement's per-minute rate limit and monthly quota | Yes |
| `pk_test_…` | The same data as a live key | Lower rate limits | No |

Use test keys for development, CI and the playground on this site, and live keys only in production services.

Pinakel issues keys when your agreement is set up. A key is shown once, when it is issued; we store only a hash of it, so we cannot show it to you again. If you lose a key, rotate it.

### Rotating a key

Rotate a key yourself in the customer portal at [portal.pinakelai.com](https://portal.pinakelai.com): open **API keys**, choose **Rotate…**, and copy the new key, which is shown once. The old key stops working within about a minute, so deploy the new key first if you can schedule the rotation. Rotate immediately if a key may have leaked, for example into a log, a ticket or a repository.

Revocation works the same way: Pinakel revokes keys on request or when an agreement ends, and requests with the key fail within about a minute.

## When authentication fails

Authentication errors are [problem details](https://docs.pinakelai.com/api-reference/errors.md). Every 401 response carries a `WWW-Authenticate` header ([RFC 6750](https://www.rfc-editor.org/rfc/rfc6750)).

| Situation | Status and type | `WWW-Authenticate` |
| - | - | - |
| No credential | 401 [`unauthenticated`](https://docs.pinakelai.com/errors/unauthenticated) | `Bearer realm="api.pinakelai.com"` |
| Only an `X-API-Key` header (the `detail` explains the fix) | 401 [`unauthenticated`](https://docs.pinakelai.com/errors/unauthenticated) | `Bearer realm="api.pinakelai.com"` |
| A key in the query string (`api_key`, `access_token`, `key`) | 401 [`unauthenticated`](https://docs.pinakelai.com/errors/unauthenticated) | `Bearer realm="api.pinakelai.com"` |
| An unknown or malformed key | 401 [`unauthenticated`](https://docs.pinakelai.com/errors/unauthenticated) | `Bearer realm="api.pinakelai.com", error="invalid_token"` |
| A revoked key | 401 [`key-revoked`](https://docs.pinakelai.com/errors/key-revoked) | `Bearer realm="api.pinakelai.com", error="invalid_token"` |
| A valid key that does not include the Data API | 403 [`product-not-enabled`](https://docs.pinakelai.com/errors/product-not-enabled) | `Bearer realm="api.pinakelai.com", error="insufficient_scope", scope="data:read"` |

A key in the query string is rejected even when it is valid, and it is removed from our request logs. Query strings end up in proxy logs, browser history and analytics tools, so never send credentials that way.

> [!WARNING]
>
> After 20 lookups of unknown keys from one IP address within a minute, that address receives 401 with a `Retry-After` header for 5 minutes, including requests with a valid key that has not been used successfully within the last minute. A misconfigured deployment that retries with a wrong key can lock out the rest of your traffic from the same egress address. Do not retry a 401 automatically.

Authentication failures (401 and 403) are not counted toward your usage.

## Using the playground on this site

Each page in the [API reference](https://docs.pinakelai.com/api-reference/introduction.md) has a **Try it** button. The playground sends requests from your browser straight to `api.pinakelai.com`; they do not pass through the documentation host. The API accepts these browser requests only from `https://docs.pinakelai.com`.

Use a `pk_test_` key in the playground. Your browser may keep the key you enter, so clear it on a shared machine.

## Keep keys on the server

A key identifies your organisation and carries your quota. Call the API from your own servers, not from browser or mobile code that end users can inspect. [Security](https://docs.pinakelai.com/guides/security.md) covers storage, separate keys per environment, and incident response.

> [!NOTE]
>
> Bearer tokens that do not start with `pk_` are reserved for OAuth 2.0 access tokens with the `data:read` scope, planned for a later release. Today, such tokens get 401 `unauthenticated`.


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