Token-based security
Token-based security restricts access to your stream by requiring a valid JWT (JSON Web Token) on every playback request. This ensures that only authenticated viewers — those who have received a token from your backend — can access the stream.
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.
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. See 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 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 (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:
{
"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.
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:
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. |