# Authentication

Every Delivery API request is authenticated with an API key that belongs to your organisation. This page explains how to send the key, what each scope unlocks, how to get keys, and how to rotate or revoke them.

## Send the key as a bearer token

Put the key in the `Authorization` header of every request:

```
Authorization: Bearer wnd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

The word `Bearer`, one space, then the key. Keys start with `wnd_live_`, which helps secret scanners find a key that was committed by mistake.

A missing header, a header in another format, or a revoked or unknown key returns `401`. If Wandura cannot check the key in time, you get `503` with `error_code` `service_unavailable` (creatives: `code` `5031`) and a `Retry-After` header: the key is fine, so retry instead of rotating it.
 The API does not use cookies, and there is no per-user identity on it: a key acts for its whole organisation.

## Scopes

Each key carries one or more scopes. An endpoint refuses a key that lacks its scope with `403`, even when the key is otherwise valid.

| Scope | Label in the portal | Unlocks | Who creates it |
|---|---|---|---|
| `metadata:read` | Read film metadata | `GET /api/delivery/v1/catalog` | You, on the **Developers** page |
| `creatives:export` | Receive exported creatives | `GET /api/delivery/v1/creatives` and `GET /api/delivery/v1/creatives/{id}` | You, on the **Developers** page |
| `webhooks:manage` | Manage webhooks | No endpoint uses this scope yet | You, on the **Developers** page |
| `playback` | Play films | `POST /api/delivery/v1/playback` | You, on the **Developers** page |

You create keys with the `playback` scope yourself, like any other key: on **Developers**, pick **Stream films in an app**. The key gets `metadata:read` and `playback`, so the same server can list your films and request tickets.

> **Warning:** If a playback key leaks, anyone can stream your licensed films. Keep it on your server only, and revoke it immediately if you think it has leaked. Every new playback key, and every rotation of one, also sends an alert to Wandura with your organisation, who created it and its prefix (never the key itself).

Give each key only the scopes it needs. A marketing sync job needs `creatives:export`, not `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). Other roles cannot manage keys.

1. Open **Developers** and find **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, for example **Stream films in an app** for a playback key, or choose the scopes yourself under **Advanced: choose scopes**.
4. Select **Create key**, then copy the key before you close the notice.

The full key is shown once. Wandura stores only a fingerprint of it and cannot show it to you again. If you lose a key, rotate it or create a new one.

The key list shows each key's prefix, label, scopes and when it was last used, so you can spot keys that are no longer in use.

## Keep keys on your server

- Call the API only from your backend. The endpoints do not send CORS headers, so browser calls fail, and a key shipped inside a web page or mobile app can be extracted.
- Store keys in a secrets manager or environment variables, never in source control.
- Use a separate key for each system and environment, so you can revoke one without touching the others.
- Never log full keys. When you talk to support, quote the key prefix shown in the portal.

## Rotate a key

Rotating replaces the secret of a key and keeps its label and scopes.

1. On **Developers**, select **Rotate** next to the key and confirm.
2. Copy the new key. It is shown once.
3. Deploy the new key to your backend.

> **Warning:** The old key stops working the moment you confirm. To rotate without downtime, create a second key with the same scopes, deploy it, and then revoke the old one.

A revoked key cannot be rotated; create a new key instead. Keys with the `playback` scope are rotated the same way, by any **Admin** or **Developer** of your organisation. For a playback key, the zero-downtime switch matters most: create a second playback key, deploy it, then revoke the old one.

## Revoke a key

Select **Revoke** next to the key and confirm. Anything using the key stops working immediately, and a revoked key cannot be restored.

Any **Admin** or **Developer** of your organisation can revoke any of its keys, including keys with the `playback` scope and keys Wandura created for you. If you suspect a playback key has leaked, revoke it immediately: that is your emergency switch. Then create a new playback key for your servers.

## Related

- [Quickstart](https://docs.wandura.ai/developers/quickstart)
- [Errors](https://docs.wandura.ai/developers/concepts/errors): the `401` and `403` responses.
- [Managing developer keys in the portal](https://docs.wandura.ai/partners/developer-keys)