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 the JWT 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.

The token can be provided in one of two ways:

• As an Authorization header with a Bearer token:

  Authorization: Bearer <JWT>

• As a token query parameter:

  ?token=<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.
iss	string	Issuer. Identifies the system that created the token.

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[]	Channel ID(s). If present, the token can exclusively be used for a channel in this list.
cc	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[]	Region code(s) using the subdivision codes defined in ISO 3166-2, only supported for US regions (e.g. "US-CA", "US-NY"). 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[]	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.
tid	string	Tracking ID. A group identifier string used to correlate viewers.
cvd	string	Custom viewer data. Arbitrary string attached to the session, e.g. an individual identifier to uniquely identify a viewer.

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 / Media player	desktop
Smart Phone / Tablet	mobile
Smart TV / Game console	tv

Example payload:

{
  "sub": "user-12345",
  "iat": 1516239022,
  "exp": 1672531200,
  "optiview": {
    "ch": ["channel_1", "channel_2"],
    "cc": ["US", "BE"],
    "rgn": ["US-CA", "US-NY"],
    "hw": ["mobile", "tv"],
    "tid": "group-abc",
    "cvd": "viewer-98765"
  }
}

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 token with each request. Refer to the platform-specific guides:

• Web
• Android
• React Native
• Roku