Skip to main content

Token based security

THEOlive offers the option to enable JWT token security for your distribution (formerly referred to as an alias). This can be interesting if you only want valid users to access your stream.

In this document, we will

  • explain how it works
  • how to enable/disable it via the console and API
  • how to configure your THEOplayer to pass the mandatory headers

How it works​

When enabling token security on a distribution, we expect you to share the shared (private) key in case of HS256/HS512 or the public key in case of RS256/RS512 encryption. This will be used on CDN level to determine if a request (with a Bearer token passed in the Authorization header) is valid or not. It's up to you to configure this header correctly through our player. Later in this document we will explain how.

In the bearer token that gets sent to us, we require the following properties to be provided in the payload:

  • exp: date in epoch format until which the JWT token is valid
  • nbf: optional date in epoch format. Stands for "not before" and acts as a "start date" of the JWT to be valid.

When not passing a bearer token for a secured distribution, the request will be rejected. If the distribution is not secured, you may still pass a token but it is not required.

token based security

Putting it all together, here is an example of a token payload:

{
  "nbf": 1750786626 // optional, viewers attempting to connect before this time will not be permitted
  "exp": 1750796626 // required, must be a valid time in the future to allow viewer access
}

To view an example token, you can paste the following token into the jwt.io debugger:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NTA4MTM5NDAsImV4cCI6MTc1MDgxNDU0MH0.hGnLRGO09AXNzMHgHLLz1HJ-9mRfDf-PnOd20w9CQmI

It was signed with the following random secret: d2e166fdda89824a6c493d8a2af7a0754199eff9e38c579cba8783767a44039c.

Enable or disable token security for an alias​

Please refer to the Enable token security for alias and Disable token security for alias API endpoints to manage the token security settings for an alias.

When enabling for the first time, you have to pass the key property in the body. If you disable token security later on, and make it active again, you can omit this property if it should stay the same.

If you're using the THEOlive management console, you can navigate to the player details page and select the alias you want to enable/disable token security for. When enabling, please pass the correct shared or public key to use. Don't forget to confirm your changes by hitting the save button!

Managing token security in the console

Configuring THEOplayer to pass the necessary headers​

Refer to our platform specific guides for details on how to setup JWT security for your channels and information on any known limitations.