Skip to content

Extend token-based security doc with optiview claim #634

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kamil-al wants to merge 2 commits into
base: main
Choose a base branch
from
+88 −1
Open

Extend token-based security doc with optiview claim #634

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f5b087e
Extend token-based security doc with optiview claim
kamil-al May 8, 2026
9a29cc8
Run Prettier
MattiasBuelens May 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 88 additions & 1 deletion theolive/distribution/security/token-based-security.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,76 @@ Token-based security restricts access to your stream by requiring a valid JWT (J

## How it works

When token security is enabled on a distribution, the CDN validates an `Authorization` header containing a Bearer token on each request. The token is signed with a shared secret (HS256/HS512) or a public/private key pair (RS256/RS512) that you provide when enabling the feature.
When token security is enabled on a distribution, the CDN validates an `Authorization` header containing a Bearer token on each request.
The token is signed with a shared secret (HS256/HS512) or a public/private key pair (RS256/RS512) that you provide when enabling the feature.

```http
Authorization: Bearer <JWT>
```

The token payload must include:

- **`exp`** — expiration time in epoch format. The token is rejected after this time.
- **`nbf`** _(optional)_ — "not before" time in epoch format. The token is rejected before this time.

Additionally, the following standard optional claims are supported:

| Claim | Type | Description |
| ----- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sub` | string | Subject. If present, a SHA-256 hash of this value is used as the viewer identity in analytics. |
| `iss` | string | Issuer. Identifies the system that created the token. |
| `aud` | string | Audience. Identifies the intended recipients of the JWT per [RFC 7519 §4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). See [Tracking token usage in Lens](#tracking-token-usage-in-lens). |

Requests without a valid token are rejected. If the distribution does not have token security enabled, the `Authorization` header is ignored.

## Custom claims

### The `optiview` claim

The JWT token supports a custom `optiview` claim that enables fine-grained access control. When present, the claim restricts token usage based on channel, geography, or device type.

| Property | Type | Description |
| -------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ch` | `string \| string[]` | Channel ID(s). If present, the token can exclusively be used for a channel in this list. |
| `cc` | `string \| string[]` | Country code(s) in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1) format (e.g. `"US"`, `"BE"`). If present, the token can exclusively be used for a country in this list. |
| `rgn` | `string \| string[]` | Region code(s) using the subdivision codes defined in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) (e.g. `"US-CA"`, `"BE-VLG"`). If present, the token can exclusively be used for a region in this list. If the viewer's region cannot be determined, the request is denied. |
| `hw` | `string \| string[]` | Device type(s). If present, the token can exclusively be used by a device type in this list. Possible values: `"desktop"`, `"mobile"`, `"tv"`. If the viewer's device type cannot be determined, this restriction is skipped. |

All properties are optional. When a property is omitted, no restriction is applied for that dimension.

#### Device type mapping

The `hw` device types are derived from the viewer's `User-Agent` header:

| Detected device | Mapped type |
| ------------------- | ----------- |
| Desktop | `desktop` |
| Media player | `desktop` |
| Mobile / smartphone | `mobile` |
| Tablet | `mobile` |
| Smart TV | `tv` |
| Game console | `tv` |

**Example payload:**

```json
{
"aud": "vendor-X",
"sub": "user-12345",
"iat": 1516239022,
"exp": 1672531200,
"optiview": {
"ch": ["channel_1", "channel_2"],
"rgn": ["US-CA", "US-NY"],
"hw": ["mobile", "tv"]
}
}
```

### Tracking token usage in Lens

The entire JWT token is forwarded to **Lens**, so any claims you include are available for analytics and filtering. Use the `aud` claim to segment and track token usage by intended audience. The `sub` claim, when present, is hashed and used as the viewer identity.

## Configuration

To enable token-based security, navigate to your distribution's security settings and enable the token security toggle. Provide the shared secret or public key used to verify tokens.
Expand All @@ -30,6 +91,13 @@ To enable token-based security, navigate to your distribution's security setting

</figure>

## Supported signing algorithms

| Algorithm family | Key type | Description |
| ---------------- | ---------------- | -------------------------------------- |
| HS256 / HS512 | HMAC (symmetric) | Signed with a shared secret. |
| RS256 / RS512 | RSA (asymmetric) | Signed with a public/private key pair. |

## Player configuration

The player needs to be configured to pass the `Authorization` header with each request. Refer to the platform-specific guides:
Expand All @@ -38,3 +106,22 @@ The player needs to be configured to pass the `Authorization` header with each r
- [Android](/theoplayer/how-to-guides/android/theolive/token-based-security/)
- [React Native](/theoplayer/how-to-guides/react-native/theolive/token-based-security/)
- [Roku](/theoplayer/how-to-guides/roku/theolive/token-based-security/)

## Error codes

When a token is rejected, the CDN returns one of the following error codes:

| Code | Description |
| ----- | -------------------------------------------------- |
| `620` | Unknown or unexpected error during JWT processing. |
| `621` | JWT required but no token provided. |
| `622` | Token could not be parsed (invalid structure). |
| `623` | Unsupported signing algorithm. |
| `624` | Current time is before the `nbf` claim. |
| `625` | Token has expired or `exp` claim is missing. |
| `626` | Signature verification failed. |
| `629` | `optiview.ch` restriction violated. |
| `630` | `optiview.dist` restriction violated. |
| `631` | `optiview.cc` restriction violated. |
| `632` | `optiview.rgn` restriction violated. |
| `633` | `optiview.hw` restriction violated. |
Loading