History: Quickstart

Every change to this page, newest first. Expand an entry to see what changed.

2 Oct 2026 · +82 −56 lines

Show changes

  # Quickstart
  
- This guide takes you from no key to a playing episode: you create an API key, list your licensed catalog, request a playback ticket for one episode and hand it to your player. Every call runs from your server. The examples use `curl` and a placeholder key; replace it with your own.
+ > **TL;DR** — **Part A** (about 5 minutes, server only): create a key, read your configuration, list your catalog. **Part B** (needs your app on a real phone with the Player SDK): get a first ticket and play an episode. A ticket cannot be tested with `curl` alone: its device values only exist on a device.
  
- ## Before you start
+ Every command below uses one environment variable, `WANDURA_API_KEY`. Part B adds `UNION_INFO` and `DRM_KEK`, copied from your app.
  
- You need:
+ ## Before you start {#before-you-start}
  
- - A member account with the **Admin** or **Developer** role in your organisation on [partner.wandura.ai](https://partner.wandura.ai).
- - An organisation that has licensed at least one film for streaming. If your catalog comes back empty, ask Wandura.
- - For playback: an API key with the `playback` scope, which you create yourself on **Developers** (pick **Stream films in an app**; if it leaks, anyone can stream your licensed films, so revoke it immediately), and the Player SDK set up in your app. Wandura registers your app IDs and issues the Player SDK licence; your organisation pays for it. The setup steps are in the Player SDK guide on partner.wandura.ai → **Developers** → **Player SDK**, available after [onboarding](before-you-start.md#get-onboarded).
+ - A member account with the **Admin** or **Developer** role in your organisation on [partner.wandura.ai](https://partner.wandura.ai). No access yet? See [Before you start](before-you-start.md#get-onboarded).
+ - At least one film licensed to your organisation, or the catalog is empty.
+ - For Part B only: the Player SDK set up in your app, with a licence for your app IDs. See [Player SDK](player-sdk/index.md).
  
- ## Step 1: Create an API key
+ ## Part A — your first calls (server only) {#part-a}
  
- 1. Sign in to [partner.wandura.ai](https://partner.wandura.ai) and open **Developers**.
- 2. Under **Create a key**, enter a label that says where the key will run, for example `cms-prod`.
- 3. Under **What will this key do?**, pick **Stream films in an app**. The key gets `metadata:read` and `playback`, so it covers every step on this page.
- 4. Select **Create key** and copy the key straight away. It is shown only once.
+ ### Step 1: Create a key {#step-1}
  
- Store the key in your secrets manager and expose it to your backend as an environment variable:
+ **Needs:** the Admin or Developer role.
  
+ 1. Sign in to partner.wandura.ai and open **Developers** → **Create a key**.
+ 2. Label it, for example `quickstart`, and pick **Stream films in an app**. The key gets `metadata:read` and `playback`.
+ 3. Select **Create key** and copy it now: it is shown once.
+ 
  ```bash
  export WANDURA_API_KEY="wnd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
  
- > **Warning:** This key can stream your licensed films. If it leaks, anyone can stream them: revoke it immediately on **Developers**. See [Authentication](authentication.md).
+ **If it fails:** no **Developers** page means your role is not Admin or Developer: ask your organisation Admin. **Next:** step 2.
  
- ## Step 2: List your catalog
+ ### Step 2: Read your configuration {#step-2}
  
+ **Needs:** the key from step 1 (any scope works).
+ 
  ```bash
+ curl -s https://www.wandura.ai/api/delivery/v1/config \
+   -H "Authorization: Bearer $WANDURA_API_KEY"
+ ```
+ 
+ **Expect** `200` with your key's scopes, your limits and the API version your key is pinned to (shortened):
+ 
+ ```json
+ {
+   "api": { "status": "beta", "version": "2026-10-02", "pinned_version": "2026-10-02", "latest_version": "2026-10-02" },
+   "key": { "scopes": ["metadata:read", "playback"] },
+   "rate_limits": { "window_seconds": 60, "doors": { "playback": { "limit": 10800, "unit": "tickets" } } },
+   "playback": { "grant_ttl_seconds": 1800, "batch": { "max_episodes": 3, "max_next": 2 } }
+ }
+ ```
+ 
+ **If it fails:** `401` = the variable is empty or the key was mistyped (`echo ${#WANDURA_API_KEY}` should print 41). `503` = retry after `Retry-After`. **Next:** step 3.
+ 
+ ### Step 3: List your catalog {#step-3}
+ 
+ **Needs:** a key with `metadata:read`.
+ 
+ ```bash
  curl -s https://www.wandura.ai/api/delivery/v1/catalog \
    -H "Authorization: Bearer $WANDURA_API_KEY"
  ```
  
- The response has two arrays. `films` is already sorted in display order. `episodes` lists every episode of those films; pick one with `"stream_ready": true` and note its `id`.
+ **Expect** `200` with `films` (in display order) and `episodes` (shortened):
  
  ```json
  {
    "films": [
-     {
-       "id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10",
-       "title": "The Heiress Returns",
-       "slug": "the-heiress-returns",
-       "display_order": 10,
-       "planned_episodes": 60,
-       "free_until_episode": 5
-     }
+     { "id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10", "title": "The Heiress Returns", "slug": "the-heiress-returns", "display_order": 10, "free_until_episode": 1 }
    ],
    "episodes": [
-     {
-       "id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e",
-       "film_id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10",
-       "episode_no": 1,
-       "status": "published",
-       "stream_ready": true
-     }
+     { "id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e", "film_id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10", "episode_no": 1, "status": "published", "stream_ready": true, "poster_url": null }
    ]
  }
  ```
  
- The example is shortened. The full field list is in the [catalog reference](reference/catalog.md).
+ Pick an episode with `"stream_ready": true` and note its `id` for Part B. Large catalog? Page it with `limit`; see [Catalog sync](guides/catalog-sync.md).
  
- ## Step 3: Request a playback ticket
+ **If it fails:** an **empty** `200` (`"films": []`) means no licence is active for your organisation yet, not a broken key: ask Wandura in your team's Discord channel. `403` = the key lacks `metadata:read`. **Next:** build the [catalog sync job](guides/catalog-sync.md), or go on to Part B.
  
- On the viewer's device, ask the Player SDK for the device ID and the device public key, and send both to your backend. Your backend then calls `POST /playback` with the `playback` key:
+ ## Part B — first ticket on a real device {#part-b}
  
+ **Needs:** your app on a real iPhone or Android phone with the Player SDK started and its licence check passed, and your playback key on your backend. Simulators and emulators do not produce usable device values.
+ 
+ > **Warning:** Every ticket Wandura issues is recorded, and with `"intent": "play"` it counts as a view of the film. Do these steps with a real device and a real test viewer, not with made-up values.
+ 
+ ### Step 4: Read the device values in your app {#step-4}
+ 
+ In your app, after the Player SDK has started, read the **device ID** and the **device public key** (the exact calls are in the Player SDK guide on the portal), and log them once in a debug build. On your backend shell:
+ 
  ```bash
+ export UNION_INFO="<device ID logged by your debug build>"
+ export DRM_KEK="<device public key logged by your debug build>"
+ ```
+ 
+ **If it fails:** a value such as `(null)` or an empty string means the SDK had not started or its licence check failed. See [Player SDK](player-sdk/index.md#common-problems).
+ 
+ ### Step 5: Request a ticket {#step-5}
+ 
+ From your backend, for the episode you picked in step 3:
+ 
+ ```bash
  curl -s -X POST https://www.wandura.ai/api/delivery/v1/playback \
-   -H "Authorization: Bearer $WANDURA_PLAYBACK_KEY" \
+   -H "Authorization: Bearer $WANDURA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "episode_id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e",
-     "union_info": "<device ID from the Player SDK>",
-     "drm_kek": "<device public key from the Player SDK>",
-     "viewer_ref": "session-7f3a91",
+     "union_info": "'"$UNION_INFO"'",
+     "drm_kek": "'"$DRM_KEK"'",
+     "viewer_ref": "qa-viewer-1:device-1",
      "intent": "play"
    }'
  ```
  
+ If `UNION_INFO` and `DRM_KEK` are empty, Wandura answers `409` `sdk_required` and issues nothing.
+ 
+ **Expect** `200`:
+ 
  ```json
  {
    "vid": "v0d2f8c1a9e4b7",
-   "play_auth_token": "eyJhbGciOi...placeholder...",
-   "expires_at": "2026-10-01T12:30:00.000Z",
+   "play_auth_token": "placeholder-play-token",
+   "expires_at": "2026-10-02T12:30:00.000Z",
    "protection": "private-encrypted",
    "subtitles": [
⋯
  ```
  
- If you leave out `union_info` and `drm_kek`, the API answers `409` with `error_code` `sdk_required`: encrypted episodes can only be played through the Player SDK.
- 
- ## Step 4: Play the episode
- 
- Return `vid`, `play_auth_token` and `subtitles` to the device. There, give the video ID and the token to the Player SDK and start playback. The SDK fetches the stream and its keys on its own.
+ **If it fails:** `400` `invalid_device_info` = a device value looks empty (`fields` says which). `403` `not_entitled` = the film is not licensed to this organisation. `404` `not_ready` = wrong `episode_id`, or the episode is not ready. All codes: [Errors](concepts/errors.md#playback-errors).
  
- ```text
- // Pseudocode — use the calls named in the Player SDK guide on the portal
- player.setVideoId(response.vid)
- player.setPlayAuthToken(response.play_auth_token)
- player.play()
- ```
+ ### Step 6: Play it {#step-6}
  
- The ticket expires at `expires_at`. Request a new one for every play start instead of caching it. See [Playback](concepts/playback.md).
+ Return `vid`, `play_auth_token` and `subtitles` to the same device. There, give the video ID and the token to the Player SDK and start playback; the SDK fetches the encrypted stream and its keys itself. A standard HLS player cannot play these episodes: it loads the playlist and stalls.
  
- > **Warning:** Never send your API key to the device, and never log the `play_auth_token`.
+ **Expect** the episode to start within a few seconds. **If it fails:** see [Player SDK · common problems](player-sdk/index.md#common-problems). The ticket expires at `expires_at` (30 minutes); asking again for the same episode on the same device with the same `viewer_ref` returns the same ticket while it has more than 5 minutes left.
  
- ## Next steps
+ ## Next steps {#next-steps}
  
- - [Authentication](authentication.md): scopes, rotation and revocation.
- - [Playback](concepts/playback.md): expiry, retries, subtitles and the `intent` field.
- - [Errors](concepts/errors.md): every error code and what to do.
+ - [Integration roadmap](integration-guide.md): the full path to go-live.
+ - [Playback flow and paywall](guides/playback-flow.md): the backend endpoint your app calls, with code.
+ - [Security](concepts/security.md): before any key reaches a server you share.

1 Oct 2026 · +3 −3 lines

Show changes

⋯
  - A member account with the **Admin** or **Developer** role in your organisation on [partner.wandura.ai](https://partner.wandura.ai).
  - An organisation that has licensed at least one film for streaming. If your catalog comes back empty, ask Wandura.
- - For playback: an API key with the `playback` scope, which Wandura issues to you, and the Player SDK set up in your app. Wandura registers your app IDs and issues the Player SDK licence; your organisation pays for it. The setup steps are in the Player SDK guide on partner.wandura.ai → **Developers** → **Player SDK**, available after [onboarding](before-you-start.md#get-onboarded).
+ - For playback: an API key with the `playback` scope, which you create yourself on **Developers** (pick **Stream films in an app**; if it leaks, anyone can stream your licensed films, so revoke it immediately), and the Player SDK set up in your app. Wandura registers your app IDs and issues the Player SDK licence; your organisation pays for it. The setup steps are in the Player SDK guide on partner.wandura.ai → **Developers** → **Player SDK**, available after [onboarding](before-you-start.md#get-onboarded).
  
  ## Step 1: Create an API key
⋯
  1. Sign in to [partner.wandura.ai](https://partner.wandura.ai) and open **Developers**.
  2. Under **Create a key**, enter a label that says where the key will run, for example `cms-prod`.
- 3. Make sure **Read film metadata** (`metadata:read`) is ticked. It is selected by default.
+ 3. Under **What will this key do?**, pick **Stream films in an app**. The key gets `metadata:read` and `playback`, so it covers every step on this page.
  4. Select **Create key** and copy the key straight away. It is shown only once.
  
⋯
  ```
  
- The key you create yourself can read the catalog but cannot play video. For step 3 you need the key with the `playback` scope that Wandura issued to you. See [Authentication](authentication.md).
+ > **Warning:** This key can stream your licensed films. If it leaks, anyone can stream them: revoke it immediately on **Developers**. See [Authentication](authentication.md).
  
  ## Step 2: List your catalog
⋯

1 Oct 2026 · +2 −2 lines

Show changes

⋯
  - A member account with the **Admin** or **Developer** role in your organisation on [partner.wandura.ai](https://partner.wandura.ai).
  - An organisation that has licensed at least one film for streaming. If your catalog comes back empty, ask Wandura.
- - For playback: an API key with the `playback` scope, which Wandura issues to you, and the Player SDK set up in your app. Wandura provides the SDK licence and registers your app's bundle ID or package name during onboarding.
+ - For playback: an API key with the `playback` scope, which Wandura issues to you, and the Player SDK set up in your app. Wandura registers your app IDs and issues the Player SDK licence; your organisation pays for it. The setup steps are in the Player SDK guide on partner.wandura.ai → **Developers** → **Player SDK**, available after [onboarding](before-you-start.md#get-onboarded).
  
  ## Step 1: Create an API key
⋯
  
  ```text
- // Pseudocode — use the calls named in your Player SDK onboarding pack
+ // Pseudocode — use the calls named in the Player SDK guide on the portal
  player.setVideoId(response.vid)
  player.setPlayAuthToken(response.play_auth_token)
⋯

1 Oct 2026 · +1 −1 lines

Show changes

⋯
  
  - A member account with the **Admin** or **Developer** role in your organisation on [partner.wandura.ai](https://partner.wandura.ai).
- - An organisation that has licensed at least one film for streaming. If your catalog comes back empty, ask your Wandura partner contact.
+ - An organisation that has licensed at least one film for streaming. If your catalog comes back empty, ask Wandura.
  - For playback: an API key with the `playback` scope, which Wandura issues to you, and the Player SDK set up in your app. Wandura provides the SDK licence and registers your app's bundle ID or package name during onboarding.
  
⋯

29 Sept 2026 · Page created