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

# Authentication

> API keys, session cookies, and the anonymous tier — how PocketUtils identifies every caller.

Every `/v1` request is identified as exactly one of three **callers**. The same route handlers serve all three — a subscriber integrating server-to-server, a signed-in user browsing pocketutils.com, and a signed-out visitor trying a tool page — so the endpoint you test in a browser is byte-for-byte the one your integration calls.

| Caller        | How it authenticates                                           | Billed against                   |
| ------------- | -------------------------------------------------------------- | -------------------------------- |
| **API key**   | `Authorization: Bearer pu_live_...` or `X-API-Key` header      | Your plan's monthly credit cycle |
| **Session**   | `access_token` cookie, set after signing in on pocketutils.com | Your plan's monthly credit cycle |
| **Anonymous** | No credential — the default when neither is present            | A small daily allowance, per IP  |

PocketUtils resolves the caller in that order: a request with a valid API key is always treated as an API-key caller, even if it also happens to carry a session cookie.

## API keys

API keys are the intended way to call PocketUtils from your own backend. A key starts with `pu_live_` followed by a random string, e.g. `pu_live_a1b2c3...`.

<Tip>
  Every code example in this documentation uses `YOUR_API_KEY` as a placeholder. Grab your real key from the [dashboard](https://pocketutils.com/profile/api-keys) and swap it in to run the requests yourself.
</Tip>

Send it in either header — they're equivalent:

<CodeGroup>
  ```bash Authorization header theme={null}
  curl https://api.pocketutils.com/v1/quota \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash X-API-Key header theme={null}
  curl https://api.pocketutils.com/v1/quota \
    -H "X-API-Key: YOUR_API_KEY"
  ```
</CodeGroup>

<Warning>
  A key's plaintext is shown exactly once, in the response to the request that created it. PocketUtils stores only its SHA-256 hash, so if you lose it there is no way to recover it — revoke the key and create a new one.
</Warning>

### Creating a key

Keys are created and managed from your [dashboard](https://pocketutils.com/profile/api-keys), not through the public API. Creating one requires a paid plan — the Free plan is the tool-page browsing allowance only, and never gets programmatic access:

| Plan       | Active API keys |
| ---------- | --------------- |
| Free       | Not available   |
| Starter    | 2               |
| Growth     | 10              |
| Scale      | Unlimited       |
| Enterprise | Unlimited       |

### Invalid or revoked keys

An API key that is malformed, unknown, or revoked is a hard failure — `401 invalid_api_key` — rather than a silent fallback to the anonymous tier. If you're integrating against the API, you want to know immediately that your credential is wrong, not discover it later as an unexplained `429`.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "That API key is not valid. Check it has not been revoked, or create a new one in your dashboard."
  }
}
```

## Session cookies

When you're signed in on pocketutils.com, the tool pages call the same `/v1` endpoints using your browser session instead of a key. This path is locked to the `pocketutils.com` origin with credentialed CORS — it isn't meant for third-party integrations, only for the website itself. If you're building an integration, use an API key.

## Anonymous access

No credential at all is a valid, supported way to call every endpoint — it's what powers trying a tool without signing up. Anonymous requests are tracked by a salted hash of the caller's IP address (raw IPs are never stored) and get:

* **10 credits per day**
* **10 requests per minute**

This is intentionally small: enough to try a couple of light endpoints, not to run an integration on. Signing in raises your allowance to the Free plan's 100 credits/month; a paid plan raises it further and unlocks API keys.

## Choosing a caller type

|             | Anonymous          | Signed in             | API key                        |
| ----------- | ------------------ | --------------------- | ------------------------------ |
| Credential  | None               | Session cookie        | `Authorization` / `X-API-Key`  |
| Credit pool | 10/day per IP      | Free: 100/month       | Paid plan: 5,000–80,000+/cycle |
| Best for    | Quick manual tries | Using pocketutils.com | Production integrations        |

<CardGroup cols={2}>
  <Card title="Rate Limits & Credits" icon="gauge-high" href="/rate-limits-and-credits">
    Full plan comparison and credit costs per endpoint.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/errors">
    Every authentication-related error code.
  </Card>
</CardGroup>


## Related topics

- [Quickstart](/quickstart.md)
- [Errors](/errors.md)
- [Introduction](/index.md)
- [Rate Limits & Credits](/rate-limits-and-credits.md)