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

Supported Integration Specification

The session api supports two request specifications.

• pallycon-apidata (aes encryption)
• jwt token authentication

If the authorization header is included in the Http Header, it operates in the JWT.

Tutorial Video

This video is a tutorial about how to generate a session URL using session manage API sample. (refer to the last part of the video)

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

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

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.

JWT Authorization Specification

You can call the Session API by setting the data issued through the token api in the Authorization header.

Authentication Token

When calling the Session API, you need to set an authentication token issued by the process below.

Step 1: Generate the base64 encoded Authorization parameter

1. Navigate to Base64 Enc/Dec page on PallyCon DevConsole.
2. While Encrypt option is selected, enter the AccountID:AccessKey value in the left text field.
3. Base64 encoded output will be displayed as the screenshot below.
4. Copy the output value to use in the next step.

You need to input the AccountID and AccessKey values for your PallyCon service account.

Step 2: Use the parameter value to generate the Authorization token.

Call the token API URL with base64 encoded value in the Authorization request header.

• URL: https://watermark.pallycon.com/api/v2/token/{siteId}
• Method: GET

Path Parameter

Request Header

Sample Request

GET /api/v2/token/DEMO HTTP/1.1
Authorization: basic authInfo
Host: watermark.pallycon.com

Response Data Fields

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 112
{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "token" : "Bearer valid-token"
  }
} 

API Request Header

You can call the Session API by setting the data issued through the token api in the authorization header.

Common Response Specifications

Response Status

Response Data Fields

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": {dash/hls},
    "cmaf": {true/false},
    "forensic_mark": {forensic_mark},
    "wmt_type": {aes/jwt},
    "prefix_folder": "wm-contents"
}

API data specification

Response

Response Data JSON Format

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

Response data specification

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

Request

• Called by PallyCon HTTP API specification
• URL : https://watermark.pallycon.com/api/v2/session/watermarkToken/{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},
    "streaming_format": {dash/hls},
    "cmaf" : {true/false}
} 

API Data Specification

Response

Response Data JSON Format

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

Response Data Specification

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

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

lastKey

data

Session Manager API error codes

Step-by-Step Guide with Example for pallycon-apidata (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.

In addition to the below step-by-step example, please also refer to our sample codes uploaded on Github.

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", 
    "prefix_folder": "wm-contents"
}

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 (Input your site key shown on PallyCon Console)
• Output format: base64 text

Result of step 2

ra2Q7t5DTIImHYsOcARkiG5/cuXfa/nB4jR3IVBRUVDZBxvqK+zQXcTv2bljMGAyt03WDXbMex5KzrSTIrDbWuDkX0juIMdngoHaS8WKX6fhDlKJ/AkBaUEcF5SkAOmfYgCs7cURH3gwgZ1rrJ6WyBD09vLoqHqAs61a5Mrqv342TYqooCjibcsSYQujXkzfAgLTD390Eiakf/MkWMVVSjw0GP3LZkbnl67SiVwo58aW6ZTz/jnlKCuoz/zicUEa58KLmPzDBJjP8i+VhdRw8Q==

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

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

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

• API URL: https://watermark.pallycon.com/api/v2/session/watermarkUrl/EXPL (EXPL should be replaced with your site ID)
• query param key: pallycon-apidata
• param value: the result of step 4

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

Example for JWT

This is a Postman Collection that allows you to call APIs using JWT. Postman Collection Guide