Session Manager API for Akamai

After pre-processing of watermark, the A/B variants of content (DASH or HLS) are mixed in real time and delivered to the client on the user’s playback request. PallyCon Forensic Watermarking service provides the session manager which generates the stream URL with the unique information of each playback session.

The service site can stream the mixed content to the client according to the session URL through Akamai CDN’s watermark integration.

graph LR;
    subgraph Content Service Site
    A[Service Backend]
    D[Origin server] -->|A/B variant stream| E(Akamai Edge)
    end
    subgraph End User
    A -->|4. Stream URL with WMT| B(Client player)
    E -->|5. Watermark embedded stream| B
    end
    subgraph PallyCon SaaS
    A -->|1. Session data with stream info| C(Session manager)
    C -->|2. Store session data| C
    C -->|3. Stream URL with WMT| A
    end

PallyCon HTTP API Specification

The HTTP API requests used by the PallyCon service follow the specifications below.

Please find the API request sample code in Packager and Sample Download page.

Request

Param Key Value
pallycon-apidata base64 Encoding ( JSON string )

Request Data JSON Format

{
    "data":"{base64 encode(aes256 cbc encrypt(API data))}",
    "timestamp":"{yyyy-mm-ddThh:mm:ssZ}",
    "hash":"{base64 encode(sha256(message format))}"
}

Request Data Specification

Name Value Required Description
data String Y AES encryption on the JSON string generated by the specification for each API, and the result value is input as a base64 string.
timestamp String Y Enter the time of the request at the GMT time zone in “yyyy-mm-ddThh: mm: ssZ” format.
hash String Y Enter the hash value generated according to the following specification.

AES256 Encryption

Aes256 encryption / decryption processing is performed as below using the site key value issued when joining PallyCon service. (Check PallyCon Console site)

  • mode : CBC
  • AES key : 32 byte (Site key issued from PallyCon Console site)
  • AES IV : fixed 16 byte (0123456789abcdef)
  • padding : pkcs7

SHA256 message Format

The input value of the SHA256 hash is a combination of the following strings.

[site access key] + [site_id] + [json.data] + [json.timestamp]
  • site access key: It is the access key value that is issued when creating PallyConsole Cloud service site. It can be checked on the PallyCon Console page.
  • The resulting value of the sha256 hash function must be entered into the base64 function as binary data, not as a string.

Session URL Request API

An API that receives the session URL to play on the client. The input values of the request are the URL of the watermark preprocessing result and the session information (forensic mark) to be inserted as a forensic watermark of the stream.

Request

  • Called by PallyCon HTTP API specification
  • URL : https://watermark.pallycon.com/api/v2/session/watermarkUrl/akamai/{site_id}
  • Method: GET

You need to replace ‘site_id’ part with your siteID issued by PallyCon console.

API Data JSON Format

{
    "domain": {domain},
    "output_path": {output_path},
    "cid": {cid},
    "streaming_format": {streaming_format},
    "forensic_mark": {forensic_mark},
    "gop": {30/60/120},
    "skipbit": {skipbit}
}

API data specification

Name Value Required Description
domain String Y Domain of content URL (e.g. cdn.yoursite.com)
output_path String Y The output_path that was entered when requesting watermark ackaging
cid String Y Unique content ID for DRM integration. If the content is non-DRM, input ny string such as ‘content’.
streaming_format String Y Streaming protocol (“dash” or “hls”)
forensic_mark String Y Session data to be inserted as watermark (such as end user ID, evice info, etc.), max 254 byte alphanumeric characters
gop Long N GOP of original video (support 30, 60, 120 GOP, default 60)
skipbit Long N The length of non-watermarked part at the start of the video (default: 4)

Response

Response Data JSON Format

{
    "error_code": {error_code},
    "error_message": {message},
    "data": {watermark_url}
}

Response data specification

Name Value Required Description
error_code String Y “0000” if succeeded, alphanumeric error code if failed
error_message String Y Error message
data String N If succeeded, returns the Session URL

Please see below for detailed Session URL format

  • Session URL format: <content CDN domain>/<WMT>/<output_path>/<cid>/<stream_format>/<manifest_file>

  • Session URL specification

    Item Description
    content CDN domain Domain name of content’s CDN. Set based on the domain in the request data
    WMT Akamai JWT Token for the watermark integration
    output_path Path of the packaging output on the storage.
    cid Unique ID of the content for DRM integration
    stream format Streaming protocol of content. (‘dash’ or ‘hls’)
    manifest file Manifest filename (‘stream.mpd’ or ‘master.m3u8’)

Error code

Code Description
0000 Succeeded
A1000 Invalid input parameter
A1002 Invalid timestamp format
A1003 Can not find the site ID
A1006 Failed to decrypt with the site key
A1007 Failed to verify the hash
A4002 Failed to store watermark data
A4003 Failed to create watermark data
A7008 API data parsing error
A7009 Invalid API version

Step-by-Step Guide with Example

The below guide shows how you can create the API request and get the response.

Note: The examples shown in this guide are for your reference only. They don’t actually work.

Step 1 - Prepare API Request Data JSON

Example JSON for the API data

{
    "domain": "cdn.service-site.com",
    "output_path": "output",
    "cid": "content1",
    "streaming_format": "dash",
    "forensic_mark": "testmark.1234567"
}

Step 2 - AES256 encryption and base64 encoding of the API data

Result of step 2

N5CNHHCgEPVDFBpgtHzraqNUzBZoy4pzx3fSDnzHDMek5AMlmWSlII67tNQ2MJP1NL+dSjQZlEnXp7+ATXOopJEdH1KIZ0jNjY19bRLl9aG0gJSsbS6krhNxuuDzLayT/CgPwQUge1hQj1U2xtXSbDFUfiXSFZtJLSlA/QdTwTC5NpxfLjBmtRspPh1AOuKNwgiS9HuJxV9f6NDK22unYvbh8/qnAWWtNTMcjgZMjkU=

Step 3 - Generate hash

  • site access key: A3DfypNw0bLgR3FAa5Q2TbS1iiUK4iIf
  • site ID: EXPL
  • api data: the result from step 2
  • timestamp: 2020-05-27T02:15:00Z

Combined string before hash

A3DfypNw0bLgR3FAa5Q2TbS1iiUK4iIfEXPLN5CNHHCgEPVDFBpgtHzraqNUzBZoy4pzx3fSDnzHDMek5AMlmWSlII67tNQ2MJP1NL+dSjQZlEnXp7+ATXOopJEdH1KIZ0jNjY19bRLl9aG0gJSsbS6krhNxuuDzLayT/CgPwQUge1hQj1U2xtXSbDFUfiXSFZtJLSlA/QdTwTC5NpxfLjBmtRspPh1AOuKNwgiS9HuJxV9f6NDK22unYvbh8/qnAWWtNTMcjgZMjkU=2020-05-27T02:15:00Z

Result of step 3

xsQVqDW04FsO43Y64Gd6EFz0l5zIrebVr1yBWUY+Nuo=

Step 4 - Build request data JSON and base64 encode

  • ‘data’: the result of step 2
  • ‘timestamp’: the same timestamp as in step 3
  • ‘hash’: the result of step 3

JSON data

{
    "data": "N5CNHHCgEPVDFBpgtHzraqNUzBZoy4pzx3fSDnzHDMek5AMlmWSlII67tNQ2MJP1NL+dSjQZlEnXp7+ATXOopJEdH1KIZ0jNjY19bRLl9aG0gJSsbS6krhNxuuDzLayT/CgPwQUge1hQj1U2xtXSbDFUfiXSFZtJLSlA/QdTwTC5NpxfLjBmtRspPh1AOuKNwgiS9HuJxV9f6NDK22unYvbh8/qnAWWtNTMcjgZMjkU=",
    "timestamp":"2020-05-27T02:15:00Z",
    "hash":"xsQVqDW04FsO43Y64Gd6EFz0l5zIrebVr1yBWUY+Nuo="
}

Result of step 4 (base64 encoded JSON)

ewogICAgImRhdGEiOiAiTjVDTkhIQ2dFUFZERkJwZ3RIenJhcU5VekJab3k0cHp4M2ZTRG56SERNZWs1QU1sbVdTbElJNjd0TlEyTUpQMU5MK2RTalFabEVuWHA3K0FUWE9vcEpFZEgxS0laMGpOalkxOWJSTGw5YUcwZ0pTc2JTNmtyaE54dXVEekxheVQvQ2dQd1FVZ2UxaFFqMVUyeHRYU2JERlVmaVhTRlp0SkxTbEEvUWRUd1RDNU5weGZMakJtdFJzcFBoMUFPdUtOd2dpUzlIdUp4VjlmNk5ESzIydW5ZdmJoOC9xbkFXV3ROVE1jamdaTWprVT0iLAogICAgInRpbWVzdGFtcCI6IjIwMjAtMDUtMjdUMDI6MTU6MDBaIiwKICAgICJoYXNoIjoieHNRVnFEVzA0RnNPNDNZNjRHZDZFRnowbDV6SXJlYlZyMXlCV1VZK051bz0iCn0=

Step 5 - Call PallyCon API URL with the data

Combined API URL

https://watermark.pallycon.com/api/v2/session/watermarkUrl/akamai/EXPL?pallycon-apidata=ewogICAgImRhdGEiOiAiTjVDTkhIQ2dFUFZERkJwZ3RIenJhcU5VekJab3k0cHp4M2ZTRG56SERNZWs1QU1sbVdTbElJNjd0TlEyTUpQMU5MK2RTalFabEVuWHA3K0FUWE9vcEpFZEgxS0laMGpOalkxOWJSTGw5YUcwZ0pTc2JTNmtyaE54dXVEekxheVQvQ2dQd1FVZ2UxaFFqMVUyeHRYU2JERlVmaVhTRlp0SkxTbEEvUWRUd1RDNU5weGZMakJtdFJzcFBoMUFPdUtOd2dpUzlIdUp4VjlmNk5ESzIydW5ZdmJoOC9xbkFXV3ROVE1jamdaTWprVT0iLAogICAgInRpbWVzdGFtcCI6IjIwMjAtMDUtMjdUMDI6MTU6MDBaIiwKICAgICJoYXNoIjoieHNRVnFEVzA0RnNPNDNZNjRHZDZFRnowbDV6SXJlYlZyMXlCV1VZK051bz0iCn0=

Response from API server (Final result)

{
    "error_message":"Success",
    "error_code":"0000",
    "url":"https://cdn.service-site.com/WMTstring/output/content1/dash/stream.mpd"
}