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

# Authentication

> API keys, scopes, and the Bearer token format

All requests to `/api/v1/*` must include an `Authorization` header with a Bearer token.

```http theme={null}
Authorization: Bearer ck_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345
```

## API key format

| Prefix     | Environment                   |
| ---------- | ----------------------------- |
| `ck_live_` | Live mode — real transactions |
| `ck_test_` | Test mode — for development   |

The suffix is 32 base62 characters. Keys are stored as a salted SHA-256 hash — if you lose a key, generate a new one. The original value cannot be recovered.

## Getting a key

1. Sign in to the dashboard.
2. Go to **API Keys**.
3. Click **New API Key**, choose a name, select the scopes you need, and copy the key immediately.

## Scopes

Each key is issued with one or more scopes. Requests that require a scope the key doesn't have return `403 permission`.

| Scope             | Grants access to                                        |
| ----------------- | ------------------------------------------------------- |
| `links:read`      | `GET /payment_links`, `GET /payment_links/{id}`         |
| `links:write`     | `POST`, `PATCH`, `DELETE /payment_links`                |
| `sessions:read`   | `GET /checkout_sessions`, `GET /checkout_sessions/{id}` |
| `sessions:write`  | `POST /checkout_sessions`                               |
| `webhooks:read`   | `GET /webhook_endpoints`, `GET /webhook_endpoints/{id}` |
| `webhooks:write`  | `POST`, `DELETE /webhook_endpoints`, test endpoint      |
| `events:read`     | `GET /events`, `GET /events/{id}`                       |
| `customers:read`  | `GET /customers`, `GET /customers/{id}`                 |
| `customers:write` | `PATCH /customers/{id}`                                 |

## Rate limiting

Requests are rate-limited per API key. The current limit is returned in the `X-RateLimit-Limit` response header. Exceeding the limit returns `429 rate_limited`.

## Error responses

An invalid or missing key returns `401 authentication`:

```json theme={null}
{
  "error": {
    "type": "authentication",
    "code": "unauthenticated",
    "message": "missing or invalid api key",
    "requestId": "req_..."
  }
}
```