# Authentication & Keys

Every request needs an API key, sent as a Bearer token:

```http
GET /api/partner/v1/events HTTP/1.1
Host: app.bettertickets.com
Authorization: Bearer btk_live_…
```

## Getting a key

Ask your BetterTickets contact for an API key.

- A key belongs to one BetterTickets account and only ever sees that account's data.
- Keys start with `btk_live_` (live) or `btk_test_` (test). Anything else is refused. See [Test vs Live](https://docs.bettertickets.com/test-vs-live.md).
- The full key is shown once, when it is issued. Store it in a secret manager or an environment variable on your server, and never commit it to source control.
- If a key leaks, ask your BetterTickets contact to revoke it and issue a new one.

## Server-to-server only

The API is built for your backend. It does not allow cross-origin browser requests (no `Access-Control-Allow-Origin` header), so a browser cannot call it, and a key must never ship in a web page, browser extension or mobile app.

For the same reason these docs have **no "Try It" console**. Use the generated cURL, Node, Python or PHP samples on each operation page from your own server or terminal.

## Scopes

Each operation needs one scope. A key without it gets `403 insufficient_scope`, and the `required` field names the missing scope.

| Scope | Allows |
|---|---|
| `events:read` | `GET /events`, `GET /events/{id}`, `GET /events/{id}/locations`, `GET /locations/{id}/availability`. Every key has it. |
| `lists:read` | `GET /lists/{id}/rows` |
| `lists:write` | `POST /lists/{id}/rows` |

List scopes are added to a key on request; ask your BetterTickets contact.

```json
{ "error": "insufficient_scope", "required": "lists:write" }
```

## Account access

- API access must be turned on for your account; otherwise every call answers `403 partner_api_disabled`.
- Custom Lists calls also need Custom Lists enabled on your account (`403 partner_lists_disabled`) and **API Access** turned on in that list's settings (`403 list_api_disabled`). See [Custom Lists](https://docs.bettertickets.com/custom-lists.md).
- If BetterTickets cannot confirm these settings for a moment, the call answers `503 FEATURE_GATE_UNAVAILABLE`. Wait `Retry-After` seconds (5 if the header is missing) and retry. See [Retrying](https://docs.bettertickets.com/errors#retrying).

## Bad keys

A missing key gets `401 missing_api_key`. A key that is unknown, revoked, expired or has the wrong prefix gets the same `401 invalid_api_key` for every case, so you cannot tell them apart from the response.

`401 invalid_api_key` always means the key was checked and refused. Do not retry it; ask your BetterTickets contact for a new key.

## When the Key Check Is Unavailable

If BetterTickets cannot check your key for a moment, the call answers `503 auth_unavailable` instead of `401`. Your key has not been judged invalid, so retry:

```http
HTTP/1.1 503 Service Unavailable
Retry-After: 5
Content-Type: application/json

{
  "error": "auth_unavailable",
  "message": "API key check is temporarily unavailable. Retry after Retry-After seconds.",
  "retryable": true,
  "retry_after_seconds": 5
}
```

Wait `Retry-After` seconds between attempts and cap the number of attempts. Retrying faster gets `429 partner_rate_limited`. See [Retrying](https://docs.bettertickets.com/errors#retrying).
