Skip to main content

Unified JWT Specifications

This document describes the detailed specifications of the Unified JWT(JSON Web Token) for secure playback and player feature control of standard content(unencrypted) and Kollus DRM content. Beyond simple playback authentication, you can define various security and convenience features directly on the customer server — such as playback speed restrictions, content exposure section settings, and watermarking — in accordance with your service policies.

JWT technical specifications​

Encryption algorithm​

Kollus VOD supports only the HMAC SHA-256(HS256) algorithm.

Header: { "alg": "HS256", "typ": "JWT" }

Authentication keys​

The following two keys are used when generating and calling a JWT.

Security key​

  • Description: A secret key used for JWT signing and verification. Be careful not to expose it externally.
  • Where to find: Kollus VOD console > [Service account] > [Custom key]
Changing the security key

To change the security key, please contact Technical Support(tech_support@catenoid.net).

Custom key (custom_key)​

  • Description: An encrypted value of the security key, used together with the security key for authentication (JWT).
  • Where to find: Kollus VOD console > [Service account] > [Custom key]
    • The value may be updated upon browser refresh; copy and apply the latest value at the time of use.

Request URL format​

https://v.kr.kollus.com/s?jwt={JWT}&custom_key={CUSTOM_KEY}
Caution
  • Standard Claim usage restrictions: Errors may occur when using Claims defined in the RFC 7519 - Registered Claim Names specification.
  • Enabling watermarking: The watermarking feature is disabled by default. To enable this feature, please contact the Account Manager(biz@catenoid.net) or Technical Support(tech_support@catenoid.net).
  • iOS full-screen mode: When switching to full screen in an iOS environment, the iOS Native player is launched.
  • Feature limitations: When playing in full screen on iOS or Samsung Internet Browser, Kollus player features such as watermark display may be restricted.

JWT Payload detailed specifications​

Required options example​

This is the basic Payload structure for a user (catenoid) to play a specific content item (vnCVPVyV).

{
  "cuid": "catenoid",
  "expt": 1703980800,
  "mc": [
    {
      "mckey": "vnCVPVyV"
    }
  ]
}

Basic options​

OptionTypeRequiredDefaultDescription
cuidstring◯-User ID
  • Used as the reference value for concurrent playback prevention, bookmarks, and resume playback (nscreen) settings.
  • Use of alphanumeric characters is recommended. Using Korean or special characters may restrict searching in the prevention log.
exptinteger◯-JWT expiration date (Unix timestamp)
  • Maximum value: 1893455999 (2029-12-31)
  • Even after expiration, content access may be allowed for up to 1 minute to account for server time differences.
mcarray◯-Array containing playback content information
next_episodeboolean-falseWhether to trigger the next episode callback
  • When set to true, the next episode callback configured for the channel is called.
  • If it is the last episode, set this value to false to disable the feature.
playback_ratesarray--List of playback speeds available to the user
  • Restrictions: PC player only; not applicable to the mobile App Player
  • Format: [playback speed list(array), number of display rows(rows)]
  • Example: [[0.5, 0.7, 1, 1.3, 1.5, 1.7, 2], 2]
    (Description: 7 playback speed options displayed in 2 rows in the UI)
playcallback_ignoreboolean-falseWhether to ignore playback callback transmission
  • When set to true, the playback callback is not sent to the server.

Content options (settings inside the mc array)​

See Also

For key (Key/ID) information, refer to the document below.

OptionTypeRequiredDefaultDescription
mckeystring◯-Media content key
mcpfstring-nullEncoding profile key
  • If not specified, the profile optimized for the playback environment is automatically selected.
titlestring-nullContent title
  • If not specified, the original file title is displayed.
intrboolean-falseWhether the content is an intro/outro video
  • When set to true, some features such as resume playback and LMS callback are restricted.
  • When downloading via DRM, only the main content file is downloaded.
seekboolean-trueWhether seeking (scrubbing) is allowed
  • When set to false, the bookmark feature is disabled.
seekable_endinteger--1End point of allowed seek range (sec)
  • -1 (default): seeking not allowed
  • Even if the seek option is false, if seekable_end is 10, seeking is allowed within the 0–10 second range.
disable_playrateboolean-falseDisable playback speed selection
  • When set to true, the playback speed selection feature is disabled.
disable_nscreenboolean-falseDisable resume playback feature
  • When set to true, the resume playback feature is disabled.
scroll_eventboolean-falseWhether to apply scroll events
  • true: fit video area based on vertical height
  • false: fit video area based on horizontal width
bookmarkboolean-trueWhether to display the bookmark button

Content exposure section settings​

Kollus VOD does not provide physical editing of the original file (cutting, merging, etc.), but you can configure a specific section of registered content to be exposed to users.

  • Feature definition: Specifies the start point (start_time) and end point (end_time) within the original video that are available for playback and distributes accordingly.
  • Key characteristics
    • No video editing: Physical data-level editing such as cutting or merging the original video file after upload is not supported.
    • Distribute specific sections: Video outside the configured section is not loaded in the user's player; only the specified section is exposed to users.
    • Flexible management: Without duplicating or re-uploading the original file, a single file can be used as multiple posts simply by changing the configuration values.
OptionTypeDefaultDescription
play_section.start_timeintegernullPlayback section start point (sec)
play_section.end_timeintegernullPlayback section end point (sec)

Subtitle settings​

Implementation guide

To expose only specific subtitles, set both the filter and show_by_filter options to true.

OptionTypeDefaultDescription
subtitle_policy.filter.namestringnullSubtitle filter - subtitle name
subtitle_policy.filter.language_codestringnullSubtitle filter - language code
subtitle_policy.filter_main.namestringnullMain subtitle filter - subtitle name
subtitle_policy.filter_main.language_codestringnullMain subtitle filter - language code
subtitle_policy.filter_sub.namestringnullSub subtitle filter - subtitle name
subtitle_policy.filter_sub.language_codestringnullSub subtitle filter - language code
subtitle_policy.show_by_filterbooleanfalseWhether to display subtitles based on filter criteria
subtitle_policy.is_showablebooleanfalseWhether to display subtitles

Watermarking​

Overlays user identification information on the screen to prevent unauthorized recording and leakage.

Note
  • Enabling the feature: The watermarking feature is disabled by default. To enable this feature, please contact the Account Manager(biz@catenoid.net) or Technical Support(tech_support@catenoid.net).
  • Tamper prevention: Protection against watermark tampering via external scripts (JavaScript Injection) is applied by default.
OptionTypeDefaultDescription
video_watermarking_code_policy.code_kindstring-Watermark display text
  • When "client_user_id" is entered, cuid is displayed; when a general string is entered, that text is displayed as-is.
video_watermarking_code_policy.font_sizeinteger7Watermark text size (px)
video_watermarking_code_policy.font_colorstring"FFFFFF"Watermark color (hex)
video_watermarking_code_policy.alphainteger200Watermark opacity (0–255)
video_watermarking_code_policy.show_timeinteger1Watermark display duration (sec)
video_watermarking_code_policy.hide_timeinteger60Watermark hidden duration (sec)
video_watermarking_code_policy.show_pausedbooleanfalseWhether to display the watermark when paused
video_watermarking_code_policy.enable_html5_playerbooleanfalseWhether to use Kollus Web Player
  • true: Plays with Kollus Web Player.
  • false: Plays with App Player for Windows.
PHP implementation example
<?php
/**
* base64_urlencode
*
* @param string $str
* @return string
*/
function base64_urlencode($str) {
    return rtrim(strtr(base64_encode($str), '+/', '-_'), '=');
}

/**
* jwt_encode
*
* @param array $payload
* @param string $key
* @return string
*/
function jwt_encode($payload, $key) {
    $jwtHead = base64_urlencode(json_encode(array('typ' => 'JWT', 'alg' => 'HS256')));
    $jsonPayload = base64_urlencode(json_encode($payload));
    $signature = base64_urlencode(hash_hmac('SHA256', $jwtHead . '.' . $jsonPayload, $key, true));

    return $jwtHead . '.' . $jsonPayload . '.' . $signature;
}

$securityKey = 'SECURITY_KEY';
$customKey = 'CUSTOM_KEY';
$mediaContentKey = 'MEDIA_CONTENT_KEY';
$clientUserId = 'CLIENT_USER_ID';
$expireTime =  7200; // 120 minutes
$mediaItems = array(
  array(
        'media_content_key' => $mediaContentKey,
    ),
);

$payload = array(
    'mc' => array(),
    'cuid' => $clientUserId,
    'expt' => time() + $expireTime,
  'video_watermarking_code_policy' =>
      array(
        'code_kind' => '2930451',
        'font_size' => 20,
        'font_color' => 'ffffff',
        'show_time' => 10,
        'hide_time' => 1,
        'alpha' => 255,
        'enable_html5_player' => true
      ),
);

foreach ($mediaItems as $mediaItem) {
    $mcClaim = array();
    $mcClaim['mckey'] = $mediaItem['media_content_key'];
    $payload['mc'][] = $mcClaim;
}

$jwtToken = jwt_encode($payload, $securityKey);

$webTokenURL = 'https://v.kr.kollus.com/s?jwt=' . $jwtToken . '&custom_key=' . $customKey;
?>

<!DOCTYPE html>
<html lang="en">
<body>
    <iframe width="840" height="472" src="<?php echo $webTokenURL; ?>" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
</body>
</html>

Usage examples​

Continuous playback of intro + main content + outro​

An example configured to play the intro, main content, and outro as a single uninterrupted piece of content.

{
  "cuid": "{END_USER_ID}",
  "expt": 1735660800,
  "mc": [
    {
      "mckey": "gDV2B1ZG",
      "intr": true
    },
    {
      "mckey": "vnCVPVyV"
    },
    {
      "mckey": "eBzkZtzG",
      "intr": true
    }
  ]
}

Continuous playback of intro followed by main content​

An example configured to disable seeking in the intro and automatically transition to the main content.

{
  "cuid": "{END_USER_ID}",
  "expt": 1735660800,
  "mc": [
    {
      "mckey": "gDV2B1ZG",
      "intr": true,
      "seek": false
    },
    {
      "mckey": "vnCVPVyV"
    }
  ]
}

Allow seeking only within the 0–30 second range​

An example that blocks full seeking but allows seeking within the first 30 seconds, useful as a preview clip.

{
  "cuid": "{END_USER_ID}",
  "expt": 1735660800,
  "mc": [
    {
      "mckey": "gDV2B1ZG",
      "intr": true,
      "seekable_end": 30,
      "seek": false
    }
  ]
}

Allow seeking only within the watched section​

An example that allows seeking only within the already-watched section and restricts arbitrary seeking into unwatched sections.

{
  "cuid": "{END_USER_ID}",
  "expt": 1735660800,
  "mc": [
    {
      "mckey": "vnCVPVyV",
      "seekable_end": 1,
      "seek": false
    }
  ]
}

Apply watermarking​

An example security policy that displays the user ID (cuid) on screen for 3 seconds and hides it for 300 seconds (5 minutes).

{
  "cuid": "{END_USER_ID}",
  "expt": 1735660800,
  "video_watermarking_code_policy": {
    "code_kind": "client_user_id",
    "font_size": 10,
    "font_color": "FFFFFF",
    "alpha": 128,
    "show_time": 3,
    "hide_time": 300
  },
  "mc": [
    {
      "mckey": "vnCVPVyV"
    }
  ]
}
Example code repository link

The full example code (PHP) is available in the Kollus GitHub repository.