# 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.

## Before you start

You need:

- 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](https://docs.wandura.ai/developers/before-you-start#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. 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.

Store the key in your secrets manager and expose it to your backend as an environment variable:

```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](https://docs.wandura.ai/developers/authentication).

## Step 2: List your catalog

```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`.

```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
    }
  ],
  "episodes": [
    {
      "id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e",
      "film_id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10",
      "episode_no": 1,
      "status": "published",
      "stream_ready": true
    }
  ]
}
```

The example is shortened. The full field list is in the [catalog reference](https://docs.wandura.ai/developers/reference/catalog).

## Step 3: Request a playback ticket

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:

```bash
curl -s -X POST https://www.wandura.ai/api/delivery/v1/playback \
  -H "Authorization: Bearer $WANDURA_PLAYBACK_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",
    "intent": "play"
  }'
```

```json
{
  "vid": "v0d2f8c1a9e4b7",
  "play_auth_token": "eyJhbGciOi...placeholder...",
  "expires_at": "2026-10-01T12:30:00.000Z",
  "protection": "private-encrypted",
  "subtitles": [
    { "lang": "en", "url": "https://cdn.example.com/subtitles/ep1-en.vtt", "format": "webvtt" }
  ]
}
```

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.

```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()
```

The ticket expires at `expires_at`. Request a new one for every play start instead of caching it. See [Playback](https://docs.wandura.ai/developers/concepts/playback).

> **Warning:** Never send your API key to the device, and never log the `play_auth_token`.

## Next steps

- [Authentication](https://docs.wandura.ai/developers/authentication): scopes, rotation and revocation.
- [Playback](https://docs.wandura.ai/developers/concepts/playback): expiry, retries, subtitles and the `intent` field.
- [Errors](https://docs.wandura.ai/developers/concepts/errors): every error code and what to do.