Streaming Usage
# Streaming Usage
## Content Access & Security
The player needs a **streamingId** (identifies the scene) and a **view token** (authorizes playback). Both can be created in your Gracia account under **Settings → Api Settings**.
> **Important.** **Settings → Api Settings** is available only for partner Gracia accounts. If you want to become a partner, write to support at `support@gracia.ai`.
Base URL: `https://streaming.gracia.ai`
### Option 1: Long-lived View Token (not recommended)
> **Not recommended.** Long-lived tokens are less secure — anyone with the token can watch the content. Use Option 2 whenever possible.
Create a view token in **Settings → Api Settings**, set the `streamingIds` it can access, optionally restrict to specific `domains`, and pass it directly to the player. No backend needed.
Only suitable for: embedded players, kiosks, demo pages where per-user access control is not needed. Always use domain whitelisting to limit exposure.
### Option 2: Short-lived Tokens via Your Backend (recommended)
Implement an endpoint on your backend that your frontend calls when a user wants to watch content. This endpoint verifies access, requests a short-lived view token from Gracia API, and returns the tokens to the frontend. The API token never leaves your server.
Best for: pay-per-view, purchases, subscriptions.
1. Create an **API token** in **Settings → Api Settings**. Store it securely on your server.
2. Implement an endpoint (e.g. `POST /api/streaming-access/{contentId}`) that authenticates the user, checks access, calls Gracia API to issue a view token, and returns `streamingId` + `viewToken`.
3. Your frontend calls this endpoint and passes the received tokens to the player.
```text
┌──────────┐ ┌──────────────┐ ┌───────────────┐ ┌──────────────────┐
│ Player │ │ Your Backend │ │ Your Database │ │ Gracia Streaming │
│ (client) │ │ │ │ │ │ API │
└────┬─────┘ └──────┬───────┘ └──────┬────────┘ └────────┬─────────┘
│ │ │ │
│ 1. User wants to │ │ │
│ watch content │ │ │
│─────────────────────>│ │ │
│ │ │ │
│ 2. Your backend │ │
│ validates access │ │
│ │ │ │
│ │ 3. Issue view token │ │
│ │ POST /view-token/issue │
│ │───────────────────────────────────────────────────>│
│ │ │ │
│ │ 4. View token + tokenId │
│ │<───────────────────────────────────────────────────│
│ │ │ │
│ │ 5. Save token state │ │
│ │ {userId, tokenId} │ |
│ │───────────────────────>│ │
│ │ │ │
│ 6. Return streaming │ │ │
│ ID + view token │ │ │
│<─────────────────────│ │ │
│ │ │ │
│ 7. Pass streamingId + viewToken to player │
│ → player handles playback │
```
When persisting issued tokens, store at least `userId` and `tokenId`, so your backend can safely update or revoke token access later.
## OpenAPI Specification
- Specification page: [Streaming View Token OpenAPI](/streaming-view-token-openapi)
- Copy the YAML from the specification page, then paste it into [Swagger Editor](https://editor.swagger.io/).
- You can also use any other Swagger/OpenAPI-compatible editors or viewers supporting the current version of the Specification.