Change history
Every change to this page, newest first. Expand an entry to see what changed.
- 2 Oct 2026 · +39 −48 lines
Show changes
# 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 + > **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**. - Put the key in the `Authorization` header of every request: + ## Send the key {#send-the-key-as-a-bearer-token} ``` ⋯ ``` - 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. + 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. - 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. + | 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. | - ## Scopes + 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](reference/behaviour.md#authentication). - 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. + ## Scopes {#scopes} - | 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 | + This is the only scope table in these docs; other pages link here. - 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. + | 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:** 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). + > **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](concepts/security.md#leaked-key). - Give each key only the scopes it needs. A marketing sync job needs `creatives:export`, not `playback`. + 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 + ## Create a key {#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. + Members with the **Admin** or **Developer** role manage keys on the **Developers** page of [partner.wandura.ai](https://partner.wandura.ai). - 1. Open **Developers** and find **Create a key**. + 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, 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 + 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. - Rotating replaces the secret of a key and keeps its label and scopes. + The key list shows each key's prefix, label, scopes and **Last used**. Step-by-step screens: [Developer keys](../partners/developer-keys.md). - 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. + ## Rotate and revoke {#rotate-a-key} - > **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. + 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](concepts/security.md#key-lifecycle). - 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 {#revoke-a-key} - ## Revoke a key + 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. - Select **Revoke** next to the key and confirm. Anything using the key stops working immediately, and a revoked key cannot be restored. + ## Keep keys on your server {#keep-keys-on-your-server} - 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. + - 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 + ## Related {#related} + - [Security](concepts/security.md) - [Quickstart](quickstart.md) - - [Errors](concepts/errors.md): the `401` and `403` responses. - - [Managing developer keys in the portal](../partners/developer-keys.md) + - [Errors](concepts/errors.md)
- 1 Oct 2026 · +7 −5 lines
Show changes
⋯ | `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 (granted by Wandura) | `POST /api/delivery/v1/playback` | Wandura only | + | `playback` | Play films | `POST /api/delivery/v1/playback` | You, on the **Developers** page | - You cannot create a key with the `playback` scope yourself. A leaked playback key would let anyone stream your licensed films, so Wandura issues these keys directly. Ask Wandura for one when you are ready to integrate playback. + 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`. ⋯ 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 at least one scope. + 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. ⋯ > **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 by Wandura: the portal marks them **Managed by Wandura** and does not offer **Rotate**. Ask in your team's Wandura Discord channel. To switch without downtime, Wandura creates a new playback key next to the old one, you deploy it, and then Wandura revokes the old key; both keys work in between. + 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. - Developers can revoke the keys created in the portal. Only an organisation **Admin** can revoke a key with the `playback` scope. Use this as an emergency switch if you suspect a playback key has leaked, then ask Wandura for a replacement. + 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 ⋯
- 1 Oct 2026 · +1 −1 lines
Show changes
⋯ > **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 by Wandura: the portal marks them **Managed by Wandura** and does not offer **Rotate**. Ask Wandura to rotate one. + A revoked key cannot be rotated; create a new key instead. Keys with the `playback` scope are rotated by Wandura: the portal marks them **Managed by Wandura** and does not offer **Rotate**. Ask in your team's Wandura Discord channel. To switch without downtime, Wandura creates a new playback key next to the old one, you deploy it, and then Wandura revokes the old key; both keys work in between. ## Revoke a key ⋯
- 1 Oct 2026 · +2 −2 lines
Show changes
⋯ | `playback` | Play films (granted by Wandura) | `POST /api/delivery/v1/playback` | Wandura only | - You cannot create a key with the `playback` scope yourself. A leaked playback key would let anyone stream your licensed films, so Wandura issues these keys directly. Ask your Wandura partner contact for one when you are ready to integrate playback. + You cannot create a key with the `playback` scope yourself. A leaked playback key would let anyone stream your licensed films, so Wandura issues these keys directly. Ask Wandura for one when you are ready to integrate playback. Give each key only the scopes it needs. A marketing sync job needs `creatives:export`, not `playback`. ⋯ > **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 by Wandura: the portal marks them **Managed by Wandura** and does not offer **Rotate**. Ask your Wandura partner contact to rotate one. + A revoked key cannot be rotated; create a new key instead. Keys with the `playback` scope are rotated by Wandura: the portal marks them **Managed by Wandura** and does not offer **Rotate**. Ask Wandura to rotate one. ## Revoke a key ⋯
- 30 Sept 2026 · +2 −1 lines
Show changes
⋯ 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`. The API does not use cookies, and there is no per-user identity on it: a key acts for its whole organisation. + 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 ⋯
- 29 Sept 2026 · Page created