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

# Authentication

> How API tokens work — creation, scopes, rotation, revocation.

## Token format

PickupBell API tokens are **UUIDv4** strings — 36 characters of hex with dashes. A token looks like:

```
550e8400-e29b-41d4-a716-446655440000
```

We never store the raw token. On creation, only a SHA-256 hash goes into the database; the plaintext is shown once and cannot be recovered. The `key_prefix` column keeps the first 8 characters (`550e8400`) so the Keys UI can label a key without exposing the secret.

## Using a token

Every authenticated request sends an `Authorization` header:

```
Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000
```

No cookies, no query parameters. The MCP server uses the same header.

## Scoping

A key carries zero or more **scopes** that authorize specific capabilities. Scopes are checked on every request by the service layer — if the key lacks the scope for the operation, you get `403 Forbidden` with `error.code = "forbidden"` and a message naming the missing scope.

See [Scopes](/scopes) for the full list. General principles:

* **Least-privilege.** Start with only what you need. You can mint a second key with different scopes rather than giving one key the union.
* **Read vs. write are split.** `:read` scopes never grant writes.
* **Billing is never exposed.** API tokens cannot read or modify subscriptions, invoices, or payment methods regardless of scope. Use the dashboard.

## Location scoping

Tokens are **location-scoped**, not account-scoped. If a user owns three locations, they mint three tokens — one per location. An API key cannot cross location boundaries even if given an overly broad scope.

Inside the token lifetime, you'll only ever see one location when you call `GET /api/v1/locations`:

```bash theme={null}
curl https://api.pickupbell.com/api/v1/locations \
  -H "Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000"
# → { "data": [ { "id": "…", "slug": "premier-hvac", … } ] }
```

## Rotating

1. Mint a new key in the dashboard with the same scope set.
2. Deploy it to your integration.
3. Revoke the old key — any request using the revoked key returns `401 Unauthorized` from the next second onward.

## Common errors

| Status | `error.code`   | Meaning                                                                     |
| ------ | -------------- | --------------------------------------------------------------------------- |
| 401    | `unauthorized` | Missing, malformed, or revoked Bearer token.                                |
| 403    | `forbidden`    | Token is valid but lacks the scope for this operation.                      |
| 404    | `not_found`    | Resource doesn't exist — or belongs to a location you don't have access to. |

For the full error model see [Errors](/errors).