Skip to main contentIBM Video Streaming Developers

Getting started


Viewer Authentication API lets you implement a custom authentication process. This prevents live and recorded videos on your account from being accessed until the viewer authenticates. The authentication process is based on JSON Web Token (JWT) standards (JWE and JWS).


To implement viewer authentication flow you need to create an application that includes the following:

  • Screens your viewers need to go through to authenticate
  • Backend code that validates these authentication requests
  • The process to redirect back to / or embed IBM Video Streaming components (player, QnA, Chat) with authentication token

Embed with Token

If you have protected pages where you want to use our embedded components, you can pass the authentication token directly to the embed URL in the vt query parameter.

Viewer Authentication Flow - Embed with Token

Redirect Flow

If you embed the player to an unprotected page or use IBM’s channel page, the player will redirect the viewer to your authentication endpoint. You need to redirect back to the ref URL (passed in query parameter) with authentication token in the vt query parameter.

Viewer Authentication Flow - Embed with Token

Viewer Authentication Settings

You can enable viewer authentication via API.

  1. Generate an RSA key pair with 2048 bits key size

  2. Set the public key and authentication URL to the content (channel or video) via API. See more

    • and store the private key in your system secure way

We recommend using different key pairs for every content.

By default, every video inherits these settings from the channel but if you want to use different authentication for a video you can set it. See more

Example to key generation:

ssh-keygen -t rsa -b 2048 -E SHA512 -m PEM -P "" -f content_1234567.key
openssl rsa -in content_1234567.key -pubout -outform PEM -out

Viewer Authentication Token

Viewer Authentication Token token is an encrypted JWT (JWE) that contains a signed JWT (JWS) with the following mandatory claims:

  • sub: Subject, the token subject (identifier of the viewer, we recommend e-mail address)
  • iat: Issued at, Unix timestamp in seconds when the token was generated. We will accept the token in the next 60 seconds from this timestamp. (We don’t accept tokens with future issued at timestamps)

The JWS is signed with your private key that you set to the content. The JWE is encrypted with Watson Media’s public key that you can get from the API. See more

Viewer Authentication Token Lifecycle

  • You can use the same token for the different components (Player, Chat, QnA)
  • You can use every token once for a component: when the component embeds reloaded (eg: viewer reload the page) you need to generate a new token.
  • The token lifetime is 60 seconds after issued

Token generation method

Viewer Authentication Flow - Embed with Token