# Authentication

> **TL;DR** — Send `Authorization: Bearer <API key>` on every request, from your servers only. Each key belongs to your organisation and carries scopes; the table below is the one place that says which scope opens which endpoint. Admins and Developers create, rotate and revoke keys themselves on partner.wandura.ai → **Developers**.

## Send the key
```
Authorization: Bearer wnd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

The word `Bearer`, one space, then the key. Keys start with `wnd_live_`, which lets secret scanners find a key committed by mistake. The examples read the key from the environment variable `WANDURA_API_KEY`; each system you run sets it to its own key.

| You get | When |
|---|---|
| `401`, no `error_code` | The header is missing or malformed, or the key is unknown or revoked. |
| `403`, no `error_code` | The key is valid but lacks the endpoint's scope. |
| `503` `service_unavailable` | Wandura could not check the key in time. The key is fine: retry after `Retry-After`, never rotate it for this. |
| `400` `unsupported_version` | Checked before the key: your `Wandura-Version` header is not a supported version. |

A key acts for its whole organisation: the API has no per-viewer identity and uses no cookies. All rules in one place: [Canonical API behaviour](https://docs.wandura.ai/v1/developers/reference/behaviour#authentication).

## Scopes
This is the only scope table in these docs; other pages link here.

| Scope | Label on the portal | Opens | How you get a key with it |
|---|---|---|---|
| `metadata:read` | Read film metadata | `GET /catalog` | **Developers** → **Sync catalog to your CMS** (or **Stream films in an app**) |
| `playback` | Play films | `POST /playback` | **Developers** → **Stream films in an app** (comes with `metadata:read`) |
| `creatives:export` | Receive exported creatives | `GET /creatives`, `GET /creatives/{id}` | **Developers** → **Receive creatives / webhooks** |
| `videos:read` | Read open video (needs an app) | `GET /videos`, `GET /videos/{id}` | **Developers** → **Stream open video (fitness…)**; the key is bound to one app you register |
| any scope | — | `GET /config` | Any valid key |
| `webhooks:manage` | Manage webhooks | Nothing: **reserved**. There are no webhooks today; poll the feeds. | Added automatically by **Receive creatives / webhooks**; it grants nothing |

> **Warning:** A key with `playback` can stream your licensed films. If it leaks, anyone can. Keep it on your server and revoke it the moment you suspect a leak: see [Security](https://docs.wandura.ai/v1/developers/concepts/security#leaked-key).

Give each key only the scopes its system needs: a catalog sync job needs `metadata:read`, a marketing job `creatives:export`, never `playback`.

## Create a key
Members with the **Admin** or **Developer** role manage keys on the **Developers** page of [partner.wandura.ai](https://partner.wandura.ai).

1. Open **Developers** → **Create a key**.
2. Enter a **Label** (up to 80 characters) that says where the key runs, for example `catalog-sync-prod`.
3. Pick what the key is for (the purposes above), or choose scopes yourself under **Advanced: choose scopes**.
4. Select **Create key** and copy the key straight away. It is shown **once**: Wandura stores only a fingerprint.

The key list shows each key's prefix, label, scopes and **Last used**. Step-by-step screens: [Developer keys](https://docs.wandura.ai/partners/developer-keys).

## Rotate and revoke
Rotate replaces a key's secret and keeps its label, scopes and dated-version pin; revoke ends it for good. Both take effect within seconds, have no grace period, and never stop tickets already issued. The timings, the zero-downtime recipe and the leaked-key runbook are on [Security](https://docs.wandura.ai/v1/developers/concepts/security#key-lifecycle).

### Revoke
Any Admin or Developer can revoke any key of the organisation, playback keys included. A revoked key cannot be restored or rotated: create a new one.

## Keep keys on your server
- Call the API only from your backend. Browser calls fail (no CORS), and a key inside an app can be extracted.
- One key per system and per environment, so you can revoke one without touching the others.
- Never log a full key. Quote the prefix when you talk to support.

## Related
- [Security](https://docs.wandura.ai/v1/developers/concepts/security)
- [Quickstart](https://docs.wandura.ai/v1/developers/quickstart)
- [Errors](https://docs.wandura.ai/v1/developers/concepts/errors)