Restricting Access to Engage Kit Assets

The Engage Kit consists of auto-generated assets that can be made public and used depending on the access policy. Specifically:

Video Content: Generates miniatures and a short video preview.
Image Content: Generates a miniature blurred image.
Audio Content: No engage kit is generated.

To secure your Engage Kit assets such as videoPreviews and snapshots, you can configure access policies at the project level. There are two types of access policies:

Unsigned: This policy allows anyone to access the Engage Kit without any validation.
Signed: This policy requires URL signing to access the Engage Kit using HMAC-SHA256 signatures. You can enable this feature directly from your panel or through the API.

ℹ️

If you want to protect your Engage Kit contents from unauthorized access, we recommend using the Signed policy.

Managing Engage Kit Access Policy via API

You can manage the Engage Kit access policy through the Fastevo API. This includes setting and retrieving the current access policy.

Setting the Engage Kit Access Policy

To set the Engage Kit access policy, you need to perform a PUT request to the following endpoint:

PUT https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/general/engageKitAccessPolicy
{
  "engageKitAccessPolicy": "{policy}"
}

Replace {policy} with one of the following values:

unsigned
signed

Example Request to Set Policy to Unsigned

PUT https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/general/engageKitAccessPolicy
{
  "engageKitAccessPolicy": "unsigned"
}

Example Request to Set Policy to Signed

PUT https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/general/engageKitAccessPolicy
{
  "engageKitAccessPolicy": "signed"
}

Retrieving the Current Engage Kit Access Policy

To retrieve the current Engage Kit access policy, you need to perform a GET request to the following endpoint:

GET https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/general/engageKitAccessPolicy

Example Response

{
  "engageKitAccessPolicy": "unsigned"
}

Signing URLs for Engage Kit Access

When using the signed access policy, URLs must be signed using HMAC-SHA256 with your project's token signing key. The signing process adds three query parameters to the URL:

X-Expires: Unix timestamp indicating when the signature expires
X-Signature: HMAC-SHA256 signature of the URL
X-Signed-Path: (Optional) Path pattern for wildcard signing

ℹ️

You can retrieve or set your token signing key through the API or your project panel. Keep this key secure as it's used to generate signatures.

Code Samples

import crypto from "crypto";
import { URL } from "url";
 
/**
 * Generates a signed URL for Engage Kit access using HMAC-SHA256.
 *
 * @param {object} options - The options for signing the URL.
 * @param {string} options.url - The full URL to be signed (e.g., 'https://683ef84b55a144aeb553b927.c.mp2.fastevo.net/684072b529b359d01c1e1925/processed/video/content/snapshots/snapshot0-engage.webp').
 * @param {string} options.tokenSigningKey - The secret key used for generating the HMAC signature.
 * @param {number} options.expirationSeconds - The duration (in seconds) for which the signature should be valid.
 * @param {string | null} [options.signedPathOverride] - Optional. Path pattern for wildcard signing (e.g., '/path/to/*').
 * @returns {string} The signed URL with signature parameters.
 * @throws {Error} if the input URL is invalid or parameters are incorrect.
 */
export function signEngageKitUrl({
  url: inputUrlString,
  tokenSigningKey,
  expirationSeconds,
  signedPathOverride = null,
}) {
  if (!inputUrlString) {
    throw new Error("Input URL is required.");
  }
  if (!tokenSigningKey || tokenSigningKey.toLowerCase() === "none") {
    return inputUrlString; // Return unsigned URL
  }
  if (typeof expirationSeconds !== "number" || expirationSeconds <= 0) {
    throw new Error("ExpirationSeconds must be a positive number.");
  }
 
  const parsedUrl = new URL(inputUrlString);
  const requestPathname = parsedUrl.pathname;
  const originalQueryParams = Array.from(parsedUrl.searchParams.entries());
  
  const expires = Math.floor(Date.now() / 1000) + expirationSeconds;
  const pathForSignature = signedPathOverride || requestPathname;
 
  // Build string to sign
  let stringToSign = pathForSignature + "\n" + expires;
  let queryStringForSigning = "";
 
  // Include query params in signature unless using wildcard path
  if (!pathForSignature.endsWith("/*")) {
    originalQueryParams.forEach(([key, value]) => {
      // Skip signature-related params
      if (["X-Signature", "X-Signed-Path", "X-Expires"].includes(key)) {
        return;
      }
      queryStringForSigning +=
        (queryStringForSigning ? "&" : "") +
        encodeURIComponent(key) + "=" + encodeURIComponent(value);
    });
 
    if (queryStringForSigning) {
      stringToSign += "\n" + queryStringForSigning;
    }
  }
 
  // Generate HMAC-SHA256 signature
  const hmac = crypto.createHmac("sha256", tokenSigningKey);
  hmac.update(stringToSign);
  const signature = hmac.digest("hex");
 
  // Build final URL with signature params
  const finalUrl = new URL(parsedUrl.origin + requestPathname);
  originalQueryParams.forEach(([key, value]) => {
    finalUrl.searchParams.append(key, value);
  });
 
  if (signedPathOverride) {
    finalUrl.searchParams.set("X-Signed-Path", signedPathOverride);
  }
  finalUrl.searchParams.set("X-Expires", expires.toString());
  finalUrl.searchParams.set("X-Signature", signature);
 
  return finalUrl.toString();
}
 
// Example usage
const tokenSigningKey = "your-token-signing-key-here";
const urlToSign = "https://683ef84b55a144aeb553b927.c.mp2.fastevo.net/684072b529b359d01c1e1925/processed/video/content/snapshots/snapshot0-engage.webp";
 
const signedUrl = signEngageKitUrl({
  url: urlToSign,
  tokenSigningKey: tokenSigningKey,
  expirationSeconds: 3600, // 1 hour
});
 
console.log("Signed URL:", signedUrl);

Signature Algorithm Details

The signature is calculated using HMAC-SHA256 with the following algorithm:

Create a string to sign in the format:
```
{path}\n{expires}[\n{query_string}]
```
- path: The URL path or the value of signedPathOverride if provided
- expires: Unix timestamp for expiration
- query_string: URL-encoded query parameters (excluded for wildcard paths ending with /*)
Generate the HMAC-SHA256 signature using your token signing key
Append the signature parameters to the URL:
- X-Signed-Path: (if using signedPathOverride)
- X-Expires: Expiration timestamp
- X-Signature: The calculated HMAC-SHA256 signature

💡

When using wildcard paths (ending with /*), query parameters are not included in the signature calculation, allowing you to sign multiple URLs with the same path pattern.

Callbacks Transcoding