From f5b087e505eb3ffe53d0218cd875e78e56a5b0cb Mon Sep 17 00:00:00 2001 From: "Allaf, Kamil" Date: Fri, 8 May 2026 17:34:13 +0200 Subject: [PATCH 1/2] Extend token-based security doc with optiview claim --- .../security/token-based-security.mdx | 89 ++++++++++++++++++- 1 file changed, 88 insertions(+), 1 deletion(-) diff --git a/theolive/distribution/security/token-based-security.mdx b/theolive/distribution/security/token-based-security.mdx index b533ec63f329..0b030b5c01a0 100644 --- a/theolive/distribution/security/token-based-security.mdx +++ b/theolive/distribution/security/token-based-security.mdx @@ -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 +``` 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. @@ -30,6 +91,13 @@ To enable token-based security, navigate to your distribution's security setting +## 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: @@ -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. | From 9a29cc8a03ff52c7ee7e897d8f058949241e2706 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Mon, 11 May 2026 10:03:11 +0200 Subject: [PATCH 2/2] Run Prettier --- .../security/token-based-security.mdx | 72 +++++++++---------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/theolive/distribution/security/token-based-security.mdx b/theolive/distribution/security/token-based-security.mdx index 0b030b5c01a0..f78fdaf50fc0 100644 --- a/theolive/distribution/security/token-based-security.mdx +++ b/theolive/distribution/security/token-based-security.mdx @@ -11,7 +11,7 @@ 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. +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 @@ -25,10 +25,10 @@ The token payload must include: 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. | +| 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. @@ -39,12 +39,12 @@ Requests without a valid token are rejected. If the distribution does not have t 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. | +| 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. @@ -52,14 +52,14 @@ All properties are optional. When a property is omitted, no restriction is appli 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` | +| Detected device | Mapped type | +| ------------------- | ----------- | +| Desktop | `desktop` | +| Media player | `desktop` | +| Mobile / smartphone | `mobile` | +| Tablet | `mobile` | +| Smart TV | `tv` | +| Game console | `tv` | **Example payload:** @@ -93,10 +93,10 @@ To enable token-based security, navigate to your distribution's security setting ## 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. | +| 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 @@ -111,17 +111,17 @@ The player needs to be configured to pass the `Authorization` header with each r When a token is rejected, the CDN returns one of the following error codes: -| Code | Description | -| --- | --- | +| 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. | +| `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. |