Creating Playback Tokens

Overview

There are two methods for generating playback tokens in Fastevo:

1. Using the PASETO Library: This method involves directly encoding a JSON object into a PASETO V4 local (PASETO v4.l) token. It is recommended for environments with heavy workloads due to its performance and scalability.
2. Using the Simplified Token Generation Endpoint: This method provides a straightforward API endpoint for generating playback tokens without dealing with the PASETO library. It is suitable for simpler implementations but not recommended for heavy workload environments.

Method 1: Using the PASETO Library

Playback tokens are created by encoding a JSON object into a PASETO V4 local (PASETO v4.l) token and appending a specific JSON-parsed footer. Libraries for creating PASETO tokens are available in various programming languages at PASETO.io (opens in a new tab).

Token Structure

The JSON object used to create the PASETO token includes the following fields:

{
  "contentId": "65e8ddc52f41619f1815a083",
  "viewerIdentifier": "uniqueViewer123",
  "exp": "2024-03-06T22:20:21.633Z",
  "iat": "2024-03-06T21:20:21.633Z",
  "protectionLevel": "standard",
  "viewerTags": ["tag1", "tag2"]
}

• contentId: This mandatory field is the ID of the content you want to protect.
• viewerIdentifier: This mandatory field is a unique identifier for the viewer. It enables you to collect statistics and view metrics specific to this viewer. It is important to avoid including any sensitive user information in this field. For security reasons, the best practice is to store the viewer identifier as a secure, salted hash of a unique identifier from your platform.
• exp: This optional field is the expiration time of the token.
• iat: This optional field is the time at which the token was issued.
• protectionLevel: This mandatory field can take the values standard, enhanced, or adaptive. Please refer to the protection levels specification for more details. Note that enhanced and adaptive are only available for enterprise plans.
• viewerTags: This optional field is an array of strings that can be used to assign tags for both statistics and SIEM rules.

Optional Fields

• playerConfiguration: This optional field specifies the name of the player configuration you want to use for the playback session. If not set, the default player configuration at the project level is used. If set to null, the base Fastevo default configuration is used. If specified, the provided player configuration is used.
• developmentMode: This optional boolean field toggles development mode on or off. For detailed information on what this entails, please visit Development Mode Details.

Token Footer

In PASETO, the footer is a base64-encoded string that is appended to the end of the token. For creating playback tokens, the footer should include a JSON object with the following content:

{
  "v": "1",
  "p": "PROJECT_ID_HERE"
}

Replace PROJECT_ID_HERE with your actual project ID.

Code Samples

import { encrypt } from "paseto-ts/v4";
import moment from "moment";
 
async function createPlayTokenForContent(
  contentId,
  viewerIdentifier,
  projectId,
  userOpts = {}
) {
  const {
    expiresInHours = "1",
    protectionLevel = "standard",
    playerConfiguration = null,
    developmentMode = false,
    viewerTags = [],
  } = userOpts;
 
  const expiresInDate = moment().add(expiresInHours, "hours").toISOString();
 
  const tokenContent = {
    contentId,
    viewerIdentifier,
    protectionLevel,
    exp: expiresInDate,
  };
 
  if (developmentMode) {
    tokenContent.developmentMode = true;
  }
 
  if (playerConfiguration !== undefined) {
    tokenContent.playerConfiguration = playerConfiguration;
  }
 
  if (viewerTags.length > 0) {
    tokenContent.viewerTags = viewerTags;
  }
 
  const footer = {
    v: "1",
    p: projectId,
  };
 
  const encryptedToken = await encrypt(
    "REPLACE_HERE_WITH_YOUR_SIGNING_KEY_SECRET",
    tokenContent,
    { footer }
  );
 
  return encryptedToken;
}
 
export default createPlayTokenForContent;

Method 2: Using the Simplified Token Generation Endpoint

For simpler implementations where you do not want to handle the PASETO library directly, Fastevo provides an endpoint to generate playback tokens. However, this method is not recommended for heavy workload environments due to potential performance limitations.

Endpoint

POST https://api.fastevo.net/api/v1/projects/mediaProtection/contents/{contentId}/generatePlaybackToken

Replace {contentId} with the actual contentId of the media content you wish to generate a token for.

Request Parameters

• contentId (path): The ID of the content you want to protect.
• body (object): The request body should include the following fields:

Mandatory Fields

• viewerIdentifier (string): Unique identifier for the viewer.
• expiresIn (string): The duration for which the token is valid. This can be specified in various formats such as 1h for one hour, 1d for one day, 1w for one week, etc.
• protectionLevel (string): The protection level for the content. Possible values are standard, enhanced, adaptive, or qualityDependant. For more details, refer to the protection levels specification.

Optional Fields

• developmentMode (boolean): Toggles development mode on or off.
• playerConfiguration (string): The name of the player configuration you want to use for the playback session. If not set, it takes the default player configuration at the project level. If set to null, it uses the base Fastevo default configuration. If specified, it takes the player configuration provided.
• viewerTags (array of strings): An array of strings that can be used to assign tags for both statistics and SIEM rules.

Example Request

{
  "viewerIdentifier": "uniqueViewer123",
  "expiresIn": "1h",
  "protectionLevel": "standard",
  "developmentMode": false,
  "playerConfiguration": "defaultPlayerConfig",
  "viewerTags": ["tag1", "tag2"]
}

Response

201 - Media Protection Playback Token

{
  "token": "string"
}

Method 3: Using JWT Tokens (Alternative Method)

JWT Token Structure

JWT tokens for MediaProtection playback follow the same structure as PASETO tokens, with one key difference: the project ID must be included in the token payload.

{
  "contentId": "65e8ddc52f41619f1815a083",
  "viewerIdentifier": "uniqueViewer123",
  "exp": 1709590821, // Unix timestamp (seconds since epoch)
  "iat": 1709587221, // Unix timestamp (seconds since epoch)
  "protectionLevel": "standard",
  "viewerTags": ["tag1", "tag2"],
  "p": "PROJECT_ID_HERE" // Project ID (required for JWT)
}

Implementation Details

• Algorithm: Use HS256 (HMAC with SHA-256)
• Secret: Use your Token Signing Key Secret
• Expiration: Standard JWT exp claim using Unix timestamps
• Project ID: Must be included as p field in the payload

Code Example

import jwt from "jsonwebtoken";
 
function createJWTPlayToken(
  contentId,
  viewerIdentifier,
  projectId,
  userOpts = {}
) {
  const {
    expiresIn = "1h",
    protectionLevel = "adaptive",
    playerConfiguration = null,
    developmentMode = false,
    viewerTags = [],
  } = userOpts;
 
  const payload = {
    contentId,
    viewerIdentifier,
    protectionLevel,
    p: projectId, // Project ID in payload
  };
 
  if (developmentMode) {
    payload.developmentMode = true;
  }
 
  if (playerConfiguration !== undefined) {
    payload.playerConfiguration = playerConfiguration;
  }
 
  if (viewerTags.length > 0) {
    payload.viewerTags = viewerTags;
  }
 
  const token = jwt.sign(payload, "REPLACE_HERE_WITH_YOUR_SIGNING_KEY_SECRET", {
    algorithm: "HS256",
    expiresIn: expiresIn,
  });
 
  return token;
}

Important Notes

• JWT tokens are verified by the same playback endpoints as PASETO tokens
• No separate API endpoint is provided for JWT token creation
• The Token Signing Key Secret is the same for both PASETO and JWT tokens