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

# Authentication

> How to authenticate with the Package Retriever API using Bearer tokens.

# Authentication

All API requests require a Bearer token in the `Authorization` header.

```bash theme={null}
curl -H "Authorization: Bearer pr_live_YOUR_KEY_HERE" \
  https://api.packageretriever.com/v1/wallet
```

## API key types

| Prefix     | Environment | Billing                  | Labels                          |
| ---------- | ----------- | ------------------------ | ------------------------------- |
| `pr_live_` | Production  | Real charges from wallet | Real, mailable labels           |
| `pr_test_` | Sandbox     | No charges               | Simulated labels (not mailable) |

Both key types use the same endpoints and return the same response shapes. The only difference is whether real carrier APIs are called and whether your wallet is charged.

## Creating API keys

1. Log in to your [Package Retriever dashboard](https://packageretriever.com/dashboard)
2. Open **Apps & Tools** from your profile menu
3. Go to the **Unleashed** tab
4. Click **Create Key**
5. Choose environment (Live or Sandbox) and permissions
6. Copy the key immediately — it won't be shown again

## Scopes

Each key has permissions (scopes) that control what it can access:

| Scope                   | What it gates                       |
| ----------------------- | ----------------------------------- |
| `rates:read`            | Rate shopping                       |
| `labels:write`          | Creating and voiding labels         |
| `labels:read`           | Viewing labels and downloading PDFs |
| `tracking:read`         | Tracking queries                    |
| `addresses:read`        | Address validation                  |
| `carrier-accounts:read` | Viewing connected carrier accounts  |
| `batches:write`         | Creating and processing batches     |
| `batches:read`          | Viewing batch status                |
| `wallet:read`           | Viewing wallet balance              |

If a request requires a scope your key doesn't have, you'll receive:

```json theme={null}
{
  "error": {
    "code": "AUTH.KEY.INSUFFICIENT_SCOPE",
    "message": "This key does not have the 'labels:write' scope required for POST /v1/labels.",
    "suggestion": "Update this key's scopes in your dashboard or create a new key with 'labels:write'.",
    "required_scope": "labels:write",
    "key_scopes": ["rates:read", "tracking:read"]
  }
}
```

## Rate limit headers

Every response includes rate limit information:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1684000000
X-Request-Id: req_k3m9d2f1x
```

The `X-Request-Id` is unique per request. Include it when contacting support.

## Key rotation

To rotate a key without downtime:

1. Create a new key with the same scopes
2. Update your application to use the new key
3. Verify the new key works
4. Revoke the old key

Keys can be revoked instantly from the dashboard. Revoked keys return `AUTH.KEY.REVOKED` immediately.