Skip to content

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

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)

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

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

Param keyValue
pallycon-apidatabase64 Encoding ( JSON string )
{
"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

KeyTypeRequiredDescription
dataStringYAES encryption on the JSON string generated by the specification for each API, and the result value is input as a base64 string.
timestampStringYEnter the time of the request at the GMT time zone in “yyyy-mm-ddThh: mm: ssZ” format.
hashStringYEnter 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 DoveRunner service. (Check DoveRunner Console site)

  • mode : CBC
  • AES key : 32 byte (Site key issued from DoveRunner 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 DoveRunner cloud service site. It can be checked on the DoveRunner 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.

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

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

ParameterFormatDescription
siteIdfour alphanumeric charactersYour DoveRunner Site ID shown on Console
NameDescription
AuthorizationBasic Auth : Basic base64encode(accountId:accessKey)

Sample Request

GET /api/v2/token/DEMO HTTP/1.1
Authorization: basic authInfo
Host: watermark.pallycon.com
Field NameTypeInfo
error_codeStringerror code
error_messageStringerror message
data.tokenStringapi auth token

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

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

Response Status

HTTP Status CodeDescription
Error codeDescription
401Incorrect JWT Token specification or user information not found
403You do not have permission to use the API.
200Success

Response Data Fields

KeytypeValue
error_codeString0000: Success / Other values indicate failure
error_messageStringError message
dataJsonApi result

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.

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

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

{
"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",
"revoke_flag": {true/false}
}

API data specification

KeyTypeRequiredDescription
domainStringYDomain of content URL (e.g. cdn.yoursite.com)
output_pathStringYThe output_path that was entered when requesting watermark packaging
cidStringYUnique content ID
streaming_formatStringYStreaming protocol (dash or hls)
cmafBooleanNcmaf file flag (default : false)
forensic_markStringYSession data to be inserted as watermark (such as end user ID, device info, etc.), max 254 byte characters
wmt_typeStringNWatermark data format used for session URL (default: aes)
- aes: DoveRunner’s own specification used for CloudFront CDN integration
- jwt: JWT format used for Akamai and Fastly CDN integration
prefix_folderStringN (Y for T&P)In case of FWM content packaged by T&P service, enter the wm-contents value here.
revoke_flagStringNRevocation applied (default: false)
{
"error_code": {error_code},
"error_message": {message},
"data": {watermark_url}
}

Response data specification

KeyTypeRequiredDescription
error_codeStringY”0000” if succeeded, alphanumeric error code if failed
error_messageStringYError message
dataStringNIf 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>

    • Revocation applied URL: <content CDN domain>/dldzkdpsxmdnjrtm/<revoke_token>.<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

    ItemDescription
    content CDN domainDomain name of content’s CDN. Set based on the domain in the request data
    dldzkdpsxmdnjrtmPre-defined keyword for CloudFront integration
    encrypted payloadEncrypted session key (payload) for CloudFront
    WMTSession key (payload) in JWT (JSON Web Token) for Akamai and Fastly
    output_pathPath of the packaging output on the storage.
    cidUnique ID of the content (ContentID)
    stream formatStreaming protocol of content. (dash or hls)
    manifest fileManifest filename (stream.mpd or master.m3u8)

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.

  • Called by DoveRunner 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 DoveRunner console.

{
"forensic_mark": {forensic_mark},
"wmt_type": {aes/jwt},
"streaming_format": {dash/hls},
"cmaf": {true/false},
"revoke_flag": {true/false}
}

API Data Specification

KeyTypeRequiredDescription
forensic_markStringYSession data to be inserted as watermark (such as end user ID, device info, etc.), max 254 byte characters
wmt_typeStringNWatermark data format used for session URL (default: aes)
- aes: DoveRunner’s own specification used for CloudFront CDN integration
- jwt: JWT format used for Akamai and Fastly CDN integration
streaming_formatStringYStreaming protocol of content. (dash or hls)
cmafBooleanNcmaf file flag (default : false)
revoke_flagStringNRevocation applied (default: false)
{
"error_code": {error_code},
"error_message": {message},
"data": {watermark_token_data}
}
  • Revocation applied Token: <revoke_token>.<encrypted payload>

Response Data Specification

KeyTypeDescription
error_codeString”0000” if succeeded, alphanumeric error code if failed
error_messageStringError Message
dataStringIf 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.

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

  • Called by DoveRunner 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 DoveRunner console.

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

KeyTypeRequiredDescription
keywordStringNWhen searching for a keyword for the result, enter a keyword that corresponds to the search type below.
search_keyword_typeStringNKeyword search type (watermark or sessionKey)
fromStringNSearch start date based on session API request time (yyyyMMddHHmmss format in GMT timezone)
toStringNSearch End Date (yyyyMMddHHmmss format in GMT timezone)
page_unitLongNNumber of items to search (default: 25)
last_keyStringNLast retrieved session key
last_created_timeStringNGeneration time of the last retrieved session key (yyyyMMddHHmmss format in GMT timezone)
{
"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

KeyTypeDescription
error_codeString“0000” if succeeded, alphanumeric error code if failed
error_messageStringError Message
countStringNumber of items retrieved
lastKeyJsonLast retrieved session key information
dataJson ArrayList of retrieved session information

lastKey

KeyTypeDescription
keyStringLast retrieved session key
createdTimeStringCreation date of the last retrieved session key (yyyyMMddHHmmss format in GMT timezone)

data

KeyTypeDescription
keyStringLast retrieved session key
forensicMarkStringWatermark information entered through session API request data (e.g. end user ID, IP address)
createdTimeStringCreation date of the last retrieved session key (yyyyMMddHHmmss format in GMT timezone)

An API that retrieves session success details generated via the Session URL API. This success information is also available on the DoveRunner Console.

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

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

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

API Data Specification

KeyTypeRequiredDescription
keywordStringNWhen searching, please enter a keyword that matches one of the search types listed below.
search_keyword_typeStringNKeyword search type (watermark or sessionKey)
fromStringNSearch start date based on session API request time (yyyyMMddHHmmss format in GMT timezone)
toStringNSearch End Date (yyyyMMddHHmmss format in GMT timezone)
page_unitLongNNumber of items to search (default: 25)
page_indexLongNPage index (default: 1)
{
"error_code": {error_code},
"error_message": {message},
"count": {watermark_url},
"data": [{
"key": {sessionKey},
"forensicMark": {watermark},
"createdTime": {YYMMDDhhmmss}
}]
}

Response Data Specification

KeyTypeDescription
error_codeString”0000” indicates success; an alphanumeric error code will be returned if the operation fails.
error_messageStringError Message
countStringNumber of items retrieved
dataJson ArrayList of retrieved session information

data

KeyTypeDescription
keyStringLast retrieved session key
forensicMarkStringWatermark information entered through session API request data (e.g. end user ID, IP address)
createdTimeStringCreation date & time of the last retrieved session key (yyyyMMddHHmmss format in GMT timezone)

An API that retrieves session failure details generated via the Session URL API. This failure information is also available on the DoveRunner Console.

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

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

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

API Data Specification

KeyTypeRequiredDescription
keywordStringNWhen searching, please enter a keyword that matches one of the search types listed below.
search_keyword_typeStringNKeyword search type (watermark or sessionKey)
fromStringNsearch start date & time based on session API request (yyyyMMddHHmmss format in GMT timezone)
toStringNSearch End Date (yyyyMMddHHmmss format in GMT timezone)
page_unitLongNNumber of items to search (default: 25)
page_indexLongNPage index (default: 1)
{
"error_code": {error_code},
"error_message": {message},
"count": {watermark_url},
"data": [{
"key": {sessionKey},
"forensicMark": {watermark},
"createdTime": {YYMMDDhhmmss}
}]
}

Response Data Specification

KeyTypeDescription
error_codeString”0000” indicates success; an alphanumeric error code will be returned if the operation fails.
error_messageStringError Message
countStringNumber of items retrieved
dataJson ArrayList of retrieved session information

data

KeyTypeDescription
errorCodeStringSession fail error code
forensicMarkStringWatermark information entered through session API request data (e.g. end user ID, IP address)
createdTimeStringCreation date of the last retrieved session key (yyyyMMddHHmmss format in GMT timezone)
error codestateCauseSolution
0000API response success
A1000API parameter errorThe parameter of the API URL is null or an invalid value was entered.Follow the API guide and enter the correct parameters to call again.
A1002Timestamp format errorInvalid format of timestamp inside pallycon-apidata.Enter the timestamp value as GMT time in the format yyyy-mm-ddThh:mm:ssZ.
A1003Site ID value not foundThe site ID is missing or an incorrect value was entered in the API parameter.Check and apply the correct site ID (four-digit alphanumeric) value on the DoveRunner Console site.
A1006Site key decryption failedThe data part of pallycon-apidata was encrypted with the wrong site key.Check and apply the correct site key value on the DoveRunner Console site.
A1007Hash verification failedThe hash value of the API request data was generated incorrectly.Apply the correct hash value by referring to the API guide document.
A1008Database connection failureFailed to connect to the database internally in the API server.
A1010Please check required request parameters.The required request parameters are missing.
A1915Site ID value errorThe site ID is missing or an incorrect value was entered in the API parameter.Check and apply the correct site ID value on the DoveRunner Console site.
A1916Watermark data length errorThe length of the watermark data entered in the forensic_mark item exceeded 254 bytes.Enter the value shorter than 254 bytes.
A1917Trial limit exceededThe session API call limit (up to 1,000) applied to the trial account has been exceeded.Switch to a commercial account or, if necessary, request a trial limit reset through the Helpdesk.
A1918Forensic watermark service suspendedTrial has expired or commercial service has been discontinued.If you are a trial customer, switch to the commercial plan or request a trial extension from the Console if necessary. If this error occurs while using the commercial plan, please contact us via Helpdesk.
A2001Missing parameter required to generate watermark URLA parameter required for the API input data is missing.Apply the correct input value by referring to the API guide document.
A2002Trial limit related errorFailed to update trial count due to database connection error.
A2003Streaming format input errorThe streaming_format input is missing or invalid.Type dash or hls exactly depending on the format of your target stream.
A2004API input data parsing failedData that does not conform to the specifications has been entered.Generate pallycon-apidata correctly by referring to the API guide document.
A2005Missing parameter required to generate watermark tokensA parameter required for the API input data is missing.Apply the correct input value by referring to the API guide document.
A4002Failed to save watermark dataFailed to save watermark data due to an internal database connection error in the API server.
A4003Watermark data creation failureFailed to generate watermark data due to an internal system error.
A5001Akamai cert key not registeredThe certification key required for Akamai CDN integration could not be found.Request Akamai cert key registration through the Helpdesk.
A5002Akamai integration token errorAn internal error has occurred with the Akamai watermark token.
A7008API data parsing failedThe value of pallycon-apidata is missing or incorrectly created.Generate pallycon-apidata correctly by referring to the API guide document.
A7009API version errorAn unsupported API version was used.Check the version information in the API URL to use the correct version.
A7010Date format errorThe date format of the parameters from and to is incorrect.Use date data in YYYY-MM-DD format.
A9001Token value is invalidJWT token value is invalid.Check the basic token format.
A9002Token payload value is invalidJWT token payload value is invalid.
A9008Account information not availableYour account has no exactly value.Check value in your account.

Step-by-Step Guide with Example for pallycon-apidata (Session URL API)

Section titled “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.

Sample TypeGitHub Link
Pythonhttps://github.com/inka-pallycon/pallycon-wm-api-request-sample-python
Javahttps://github.com/inka-pallycon/pallycon-wm-api-request-sample-java
{
"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

Section titled “Step 2 - AES256 encryption of the API data”
ra2Q7t5DTIImHYsOcARkiG5/cuXfa/nB4jR3IVBRUVDZBxvqK+zQXcTv2bljMGAyt03WDXbMex5KzrSTIrDbWuDkX0juIMdngoHaS8WKX6fhDlKJ/AkBaUEcF5SkAOmfYgCs7cURH3gwgZ1rrJ6WyBD09vLoqHqAs61a5Mrqv342TYqooCjibcsSYQujXkzfAgLTD390Eiakf/MkWMVVSjw0GP3LZkbnl67SiVwo58aW6ZTz/jnlKCuoz/zicUEa58KLmPzDBJjP8i+VhdRw8Q==
  • site access key: A3DfypNw0bLgR3FAa5Q2TbS1iiUK4iIf (Input your access key shown on DoveRunner Console)
  • site ID: EXPL (Input your site ID shown on DoveRunner Console)
  • api data: the result from step 2
  • timestamp: 2021-09-07T02:15:00Z
A3DfypNw0bLgR3FAa5Q2TbS1iiUK4iIfEXPLN5CNHHCgEPVDFBpgtHzraqNUzBZoy4pzx3fSDnzHDMek5AMlmWSlII67tNQ2MJP1NL+dSjQZlEnXp7+ATXOopJEdH1KIZ0jNjY19bRLl9aG0gJSsbS6krhNxuuDzLayT/CgPwQUge1hQj1U2xtXSbDFUfiXSFZtJLSlA/QdTwTC5NpxfLjBmtRspPh1AOuKNwgiS9HuJxV9f6NDK22unYrzZyq6HG+qNEY6O3kp8GdRkdTU62U4t9J/byiAtEkLT2021-09-07T02:15:00Z
Z4f4gAJPeJUytea8f4DXg7jz+vAkmzNVQEiaU7QO3tA=

Step 4 - Build request data JSON and base64 encode

Section titled “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
{
"data": "N5CNHHCgEPVDFBpgtHzraqNUzBZoy4pzx3fSDnzHDMek5AMlmWSlII67tNQ2MJP1NL+dSjQZlEnXp7+ATXOopJEdH1KIZ0jNjY19bRLl9aG0gJSsbS6krhNxuuDzLayT/CgPwQUge1hQj1U2xtXSbDFUfiXSFZtJLSlA/QdTwTC5NpxfLjBmtRspPh1AOuKNwgiS9HuJxV9f6NDK22unYrzZyq6HG+qNEY6O3kp8GdRkdTU62U4t9J/byiAtEkLT",
"timestamp":"2021-09-07T02:15:00Z",
"hash":"Z4f4gAJPeJUytea8f4DXg7jz+vAkmzNVQEiaU7QO3tA="
}
ewogICAgImRhdGEiOiAiTjVDTkhIQ2dFUFZERkJwZ3RIenJhcU5VekJab3k0cHp4M2ZTRG56SERNZWs1QU1sbVdTbElJNjd0TlEyTUpQMU5MK2RTalFabEVuWHA3K0FUWE9vcEpFZEgxS0laMGpOalkxOWJSTGw5YUcwZ0pTc2JTNmtyaE54dXVEekxheVQvQ2dQd1FVZ2UxaFFqMVUyeHRYU2JERlVmaVhTRlp0SkxTbEEvUWRUd1RDNU5weGZMakJtdFJzcFBoMUFPdUtOd2dpUzlIdUp4VjlmNk5ESzIydW5ZcnpaeXE2SEcrcU5FWTZPM2twOEdkUmtkVFU2MlU0dDlKL2J5aUF0RWtMVCIsCiAgICAidGltZXN0YW1wIjoiMjAyMS0wOS0wN1QwMjoxNTowMFoiLAogICAgImhhc2giOiJaNGY0Z0FKUGVKVXl0ZWE4ZjREWGc3anordkFrbXpOVlFFaWFVN1FPM3RBPSIKfQ==

Step 5 - Call DoveRunner API URL with the data

Section titled “Step 5 - Call DoveRunner API URL with the data”
https://watermark.pallycon.com/api/v2/session/watermarkUrl/EXPL?pallycon-apidata=ewogICAgImRhdGEiOiAiTjVDTkhIQ2dFUFZERkJwZ3RIenJhcU5VekJab3k0cHp4M2ZTRG56SERNZWs1QU1sbVdTbElJNjd0TlEyTUpQMU5MK2RTalFabEVuWHA3K0FUWE9vcEpFZEgxS0laMGpOalkxOWJSTGw5YUcwZ0pTc2JTNmtyaE54dXVEekxheVQvQ2dQd1FVZ2UxaFFqMVUyeHRYU2JERlVmaVhTRlp0SkxTbEEvUWRUd1RDNU5weGZMakJtdFJzcFBoMUFPdUtOd2dpUzlIdUp4VjlmNk5ESzIydW5ZcnpaeXE2SEcrcU5FWTZPM2twOEdkUmtkVFU2MlU0dDlKL2J5aUF0RWtMVCIsCiAgICAidGltZXN0YW1wIjoiMjAyMS0wOS0wN1QwMjoxNTowMFoiLAogICAgImhhc2giOiJaNGY0Z0FKUGVKVXl0ZWE4ZjREWGc3anordkFrbXpOVlFFaWFVN1FPM3RBPSIKfQ==
{
"error_message":"Success",
"error_code":"0000",
"url":"https://cdn.service-site.com/wm-contents/OHVPUw4N4tUoc-wlcA72aX6Hj5a_v-HuXcLAbFwYSpwDDsiVdSLNbWnbjkVvTX20yiKw7U6nOmJzZaDep1_3YJYxfvHzof01IAVgAguBhGk=/output/ddb2b84b-c3ce-4f37-9182-c36f83fc3fce/dash/stream.mpd"
}

This is a Postman Collection that allows you to call APIs using JWT. Please refer to Postman Collection Guide for more details.

Collection JSON file Environment JSON file