Session Manager API Guide

After pre-processing of watermark, the ‘0’ and ‘1’ versions 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 mixed content URL with the information of the playback session.

The service site can stream the mixed content to the client according to the mixed URL through CDN integration such as Amazon CloudFront and Akamai CDN.

sequenceDiagram
    participant B as Service site
    participant D as PallyCon service
    B ->> D: Content URL, Session data
    Note right of D: Session manager
    D -->> D: Generate session key(payload) and store session data
    D ->> B: Send Session URL

The session manager API uses the following common specifications:

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 Sample Download page.

Request

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

Request Data JSON Format

{
    "data":"{aes256 cbc encryption of 'API data' for each API, and base64 encoding}",
    "timestamp":"{yyyy-mm-ddThh:mm:ssZ}",
    "hash":"{sha256 hash of 'message format' in base64 string}"
}

Request Data Specification

Key Type 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 a binary data, not as a string.

Session URL API

An API that requests the session URL to play watermarked video 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 : watermark.pallycon.com/api/v2/session/watermarkUrl/{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},
    "wmt_type": {aes/jwt}
}

API data specification

Key Type 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 packaging
cid String Y Unique content ID
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, device info, etc.), max 254 byte characters
wmt_type String Y Watermark data format used for session URL (default: aes)
- aes: PallyCon’s own specification used for CloudFront CDN integration
- jwt: JWT format used for Akamai and Fastly CDN integration

Response

Response Data JSON Format

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

Response data specification

Key Type 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

  • URL format for CloudFront (aes type): <content CDN domain>/dldzkdpsxmdnjrtm/<encrypted payload>/<output_path>/<cid>/<stream_format>/<manifest file>

  • URL format for Akamai/Fastly (jwt type): <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
    dldzkdpsxmdnjrtm Pre-defined keyword for CloudFront integration
    encrypted payload Encrypted session key (payload) for CloudFront
    WMT Session key (payload) in JWT (JSON Web Token) for Akamai and Fastly
    output_path Path of the packaging output on the storage.
    cid Unique ID of the content (ContentID)
    stream format Streaming protocol of content. (dash or hls)
    manifest file Manifest filename (stream.mpd or master.m3u8)

Watermark Token API

API to directly request watermark token data (Encrypted payload or WMT) used in Session URL. This can be used when you want to construct a session URL with an arbitrary specification, instead of using the Session URL API with a fixed format such as content path, CID, and streaming type.

To play a session URL arbitrarily configured through the Watermark Token API, you need to implement the CDN Edge’s watermark embedding (A/B Switching) logic yourself. Therefore, the token API can only be used if the customer directly implements or customizes the watermark embedding on the CDN edge.

When using the CloudFront sample provided by PallyCon or Akamai CDN integration, we recommend using the Session URL API instead of the Token API.

Request

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

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

API Data JSON Format

{
    "forensic_mark": {forensic_mark},
    "wmt_type": {aes/jwt}
} 

API Data Specification

Key Type Required Description
forensic_mark String Y Session data to be inserted as watermark (such as end user ID, device info, etc.), max 254 byte characters
wmt_type String Y Watermark data format used for session URL (default: aes)
- aes: PallyCon’s own specification used for CloudFront CDN integration
- jwt: JWT format used for Akamai and Fastly CDN integration

Response

Response Data JSON Format

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

Response Data Specification

Key Type Description
error_code String “0000” if succeeded, alphanumeric error code if failed
error_message String Error Message
data String If successful, depending on the value of the wmt_type in the request data, either Encrypted Payload for CloudFront integration or WMT token value for Akamai/Fastly integration is returned.

Session List API

An API that can inquire the session information created through the Session URL API. The same information can be viewed on the PallyCon Console site as well.

Request

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

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

API Data JSON Format

{
    "keyword": {search keyword},
    "search_keyword_type": {watermark, sessionKey},
    "from": {yyyymmddhhmmss},
    "to": {yyyymmddhhmmss},
    "page_unit": {long value},
    "last_key": {string},
    "last_created_time": {yyyymmddhhmmss}
}

API Data Specification

Key Type Required Description
keyword String N When searching for a keyword for the result, enter a keyword that corresponds to the search type below.
search_keyword_type String N Keyword search type (watermark or sessionKey)
from String Y Search start date based on session API request time (yyyyMMddHHmmss format in GMT timezone)
to String Y Search End Date (yyyyMMddHHmmss format in GMT timezone)
page_unit Long Y Number of items to search
last_key String N Last retrieved session key
last_created_time String N Generation time of the last retrieved session key (yyyyMMddHHmmss format in GMT timezone)

Response

Response Data JSON Format

{
    "error_code": {error_code},
    "error_message": {message},
    "count": {watermark_url},
    "lastKey": {
        "key": {sessionKey},
        "createdTime": {YYMMDDhhmmss}
    },
    "data": [{
        "key": {sessionKey},
        "forensicMark": {watermark},
        "createdTime": {YYMMDDhhmmss}
    }]
} 

Response Data Specification

Key Type Description
error_code String “0000” if succeeded, alphanumeric error code if failed
error_message String Error Message
count String Number of items retrieved
lastKey Json Last retrieved session key information
data Json Array List of retrieved session information

lastKey

Key Type Description
key String Last retrieved session key
createdTime String Creation date of the last retrieved session key (yyyyMMddHHmmss format in GMT timezone)

data

Key Type Description
key String Last retrieved session key
forensicMark String Watermark information entered through session API request data (e.g. end user ID, IP address)
createdTime String Creation date of the last retrieved session key (yyyyMMddHHmmss format in GMT timezone)

API Error codes

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
A5001 Required to register Akamai certification keys
A5002 Akamai watermark token error
A7008 API data parsing error
A7009 Invalid API version
A7010 Invalid date format
A7011 Failed to create mixed manifest
A7012 Failed to get manifest
A7013 Not supported streaming format
A7014 Invalid properties file key value
A7015 Empty value is not allowed
A7016 forensic_mark must be under 254 bytes
A7017 Number of session URL API call exceeded trial limit (1,000)

Step-by-Step Guide with Example (Session URL API)

The guide below shows step-by-step how to generate request data and get a response for the Session URL API. Other APIs, such as Session List API, can be applied in a similar way.

The input values used in the example are for reference only. For actual operation, you must enter the values corresponding to your PallyCon account.

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",
    "wmt_type": "aes"
}

Step 2 - AES256 encryption of the API data

Result of step 2

N5CNHHCgEPVDFBpgtHzraqNUzBZoy4pzx3fSDnzHDMek5AMlmWSlII67tNQ2MJP1NL+dSjQZlEnXp7+ATXOopJEdH1KIZ0jNjY19bRLl9aG0gJSsbS6krhNxuuDzLayT/CgPwQUge1hQj1U2xtXSbDFUfiXSFZtJLSlA/QdTwTC5NpxfLjBmtRspPh1AOuKNwgiS9HuJxV9f6NDK22unYrzZyq6HG+qNEY6O3kp8GdRkdTU62U4t9J/byiAtEkLT

Step 3 - Generate hash

  • site access key: A3DfypNw0bLgR3FAa5Q2TbS1iiUK4iIf (Input your access key shown on PallyCon Console)
  • site ID: EXPL (Input your site ID shown on PallyCon Console)
  • api data: the result from step 2
  • timestamp: 2021-09-07T02:15:00Z

Combined string before hash

A3DfypNw0bLgR3FAa5Q2TbS1iiUK4iIfEXPLN5CNHHCgEPVDFBpgtHzraqNUzBZoy4pzx3fSDnzHDMek5AMlmWSlII67tNQ2MJP1NL+dSjQZlEnXp7+ATXOopJEdH1KIZ0jNjY19bRLl9aG0gJSsbS6krhNxuuDzLayT/CgPwQUge1hQj1U2xtXSbDFUfiXSFZtJLSlA/QdTwTC5NpxfLjBmtRspPh1AOuKNwgiS9HuJxV9f6NDK22unYrzZyq6HG+qNEY6O3kp8GdRkdTU62U4t9J/byiAtEkLT2021-09-07T02:15:00Z

Result of step 3

Z4f4gAJPeJUytea8f4DXg7jz+vAkmzNVQEiaU7QO3tA=

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/QdTwTC5NpxfLjBmtRspPh1AOuKNwgiS9HuJxV9f6NDK22unYrzZyq6HG+qNEY6O3kp8GdRkdTU62U4t9J/byiAtEkLT",
    "timestamp":"2021-09-07T02:15:00Z",
    "hash":"Z4f4gAJPeJUytea8f4DXg7jz+vAkmzNVQEiaU7QO3tA="
}

Result of step 4 (base64 encoded JSON)

ewogICAgImRhdGEiOiAiTjVDTkhIQ2dFUFZERkJwZ3RIenJhcU5VekJab3k0cHp4M2ZTRG56SERNZWs1QU1sbVdTbElJNjd0TlEyTUpQMU5MK2RTalFabEVuWHA3K0FUWE9vcEpFZEgxS0laMGpOalkxOWJSTGw5YUcwZ0pTc2JTNmtyaE54dXVEekxheVQvQ2dQd1FVZ2UxaFFqMVUyeHRYU2JERlVmaVhTRlp0SkxTbEEvUWRUd1RDNU5weGZMakJtdFJzcFBoMUFPdUtOd2dpUzlIdUp4VjlmNk5ESzIydW5ZcnpaeXE2SEcrcU5FWTZPM2twOEdkUmtkVFU2MlU0dDlKL2J5aUF0RWtMVCIsCiAgICAidGltZXN0YW1wIjoiMjAyMS0wOS0wN1QwMjoxNTowMFoiLAogICAgImhhc2giOiJaNGY0Z0FKUGVKVXl0ZWE4ZjREWGc3anordkFrbXpOVlFFaWFVN1FPM3RBPSIKfQ==

Step 5 - Call PallyCon API URL with the data

Combined API URL

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

Response from API server (Final result)

{
    "error_message":"Success",
    "error_code":"0000",
    "url":"https://cdn.service-site.com/dldzkdpsxmdnjrtm/OHVPUw4N4tUoc-wlcA72aX6Hj5a_v-HuXcLAbFwYSpwDDsiVdSLNbWnbjkVvTX20yiKw7U6nOmJzZaDep1_3YJYxfvHzof01IAVgAguBhGk=/output/ddb2b84b-c3ce-4f37-9182-c36f83fc3fce/dash/stream.mpd"
}
Next