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' in base64 string}",
    "timestamp":"{yyyy-mm-ddThh:mm:ssZ}",
    "hash":"{sha256 hash of 'message format' in base64 string}"
}

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

CloudFront 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 : 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}
}

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

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>/dldzkdpsxmdnjrtm/<encrypted payload>/<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
`encrypted payload`	Encrypted session key (payload)
`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’)

Akamai Session URL Request API

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}
}

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

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
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 (CloudFront version)

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 of the API data

Where to test : https://www.devglan.com/online-tools/aes-encryption-decryption
Mode: CBC
Key size: 256
IV: 0123456789abcdef
Secret key: cUk29dLagiJ0FGiK681tFIR75ETESe0S (site key of PallyCon account)
Output format: base64 text

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

sha256 + base64 output - where to test: https://hash.online-convert.com/sha256-generator

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

API URL: https://watermark.pallycon.com/api/v2/session/watermarkUrl/EXPL
query param key: pallycon-apidata
param value: the result of step 4

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/dldzkdpsxmdnjrtm/OHVPUw4N4tUoc-wlcA72aX6Hj5a_v-HuXcLAbFwYSpwDDsiVdSLNbWnbjkVvTX20yiKw7U6nOmJzZaDep1_3YJYxfvHzof01IAVgAguBhGk=/output/ddb2b84b-c3ce-4f37-9182-c36f83fc3fce/dash/stream.mpd"
}

Last updated on Jun 24, 2021