Skip to content

DoveRunner Service API Guide

Customers of DoveRunner service can check various data such as content packaging and license issuance on DoveRunner Web Console. But there are also cases that API-based data access is needed. So we provide DoveRunner Service API to allow the customers integrate our server-side data with their system.

This document describes how to use the PallCon Service API V2 which was released in December 2021.

DoveRunner Service API uses JSON Web Token(JWT) for secure transmission of information.

You can create and test the token using an online JWT tool or a server-side programming language.

Service API JWT Specification

The token should be signed using an account-specific secret key with HMAC SHA256(HS256) algorithm. Please create a ticket on Helpdesk to get your Service API Key and the account seq value used in the token payload.

As shown on the above image, an encoded JWT token has the following format:

Terminal window
base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + HS256 signature value

The token uses json payload data as below example:

{
"sub" : "PallyConAPI",
"aud" : "INKA",
"iss" : "PallyCon",
"account_id" : "Your DoveRunner account ID",
"account_seq": "Your DoveRunner account SEQ",
"exp": 1583191411
}
KeyRequiredValue
subYFixed value as PallyConAPI
audYFixed value as INKA
issYFixed value as PallyCon
account_idYYour account ID of DoveRunner service
account_seqYYour DoveRunner account’s SEQ (can be requested via Helpdesk ticket)
expNExpiration date of the token (type: date number)

SEQ is a key value used to index key data in DoveRunner service API.

When calling the DoveRunner Service API, you’ll get one of the HTTP status codes listed below.

HTTP Status CodeDescription
401JWT Token specification is incorrect or the user information cannot be found
403Do not have permission for the called API
200HTTP communication success

When the HTTP status code is 200 (HTTP communication success), you’ll get the below response data in JSON format.

KeyTypeValue
error_codeString0000: Success / other numbers: failure
error_messageStringShows the error message on failed request
dataJSONResult of the successful API request

These APIs are for managing DoveRunner service account and sites.

This API retrieves the list of sites under the DoveRunner account.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYFixed API code as UC011004100
KeyTypeDescription
site_idStringUnique ID of the site (four alphanumeric characters)
service_nameStringName of the service site
product_listArrayProduct List
product_list.[].service_codeStringService code ( PD001 : DRM, PD002 : FWM )
product_list.[].status_codeStringService Status (SE000 : In service, SE001 : Suspended )

This API requests additional service site for the account. (in case of multiple service sites in an account)

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYAPI code value as UA010310200
service_nameStringYName of the additional service site
KeyTypeDescription
seqIntSequence number of the request

This API returns the status of request for additional service site.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYAPI code value as UA010310100
fromStringNStart date of the search (YYYY-MM-DD)
toStringNEnd date of the search (YYYY-MM-DD)
req_statusStringNStatus of the request
search_typeStringNType of the search (account_id, site_id)
search_keywordStringNKeyword for the search (used when search_type is set)
page_unitIntNNumber of search result (default:25, max: 1000)
page_indexIntNIndex of result page when the results are more than page_unit
KeyTypeDescription
seqIntSequence number of the request
account_idStringID of the service account
site_idStringID of the service site
service_nameStringName of the service site
statusStringStatus of the additional site request
update_timeStringDatetime of the status update
reg_timeStringDatetime of the request registration

This API returns the list of sub-members in an account.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYAPI code value as UA010700200
page_unitIntNNumber of search result (default:25, max: 1000)
page_indexIntNIndex of result page when the results are more than page_unit
KeyTypeDescription
group_nameStringThe sub-member’s group name
group_seqIntSequence number of the group (refer to the below table)
member_seqIntSequence number of the sub-member
member_emailStringEmail address of the sub-member
status_codeStringStatus code (MT001: active member, MT002: inactive)
reg_dateStringDate of the sub-member registration (YYYY-MM-DD)
  • Group SEQ List | Group seq | Description | | :----- | :------- | | 1000 | BIZ Group. Can access service usage history, integration information and payment related pages. | | 1001 | TS Group. Can access service usage history, integration information and SDK download pages. | | 1014 | Clients Group. Can access service usage history pages only. |

This API creates a sub-member in an account.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYAPI code value as UA010700200
member_emailStringYEmail address of the sub-member
group_seqIntNSequence number of a member group to set
KeyTypeDescription
member_seqIntSequence number of the sub-member

This API resets password of a sub-member.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYAPI code value as UA010700200
member_seqIntYSequence number of the sub-member

This API returns the default response data.

This API updates a sub-member’s information such as group and status.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYAPI code value as UA010700200
member_seqIntYSequence number of the sub-member
member_statusStringNStatus code to apply (MT001: active, MT002: inactive)
group_seqIntNSequence number of a member group to set

This API returns the default response data.

Describes the service APIs that are common to multiple products in DoveRunner service.

Get the status of a service status change request

Section titled “Get the status of a service status change request”

This API returns the status of service status change request. (for the latest request)

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYFixed code of the API (UC011004100)
site_idPathVariableYSITE ID
service_codeStringYService Code (PD001:DRM, PD002:FWM)
KeyTypeDescription
site_idStringSite ID
req_group_idStringRequest ID (PK)
reg_typeStringRequest Type Code
reg_messageStringRequest Message
reg_statusStringRequest Status (ST001: Request, ST002: Cancel, ST003:Approve)
reg_idStringRegister ID
reg_dtStringRegister Date (UTC +00:00 기준)
update_dtStringUpdate Date (UTC +00:00 기준)

This API registers requests to change the status of product services.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYFixed code of the API (UC011004100)
site_idPathVariableYSITE ID
service_codeStringYService Code (PD001:DRM, PD002:FWM)
request_typeStringYRequest Type Code (SM001: service resume request, SM002: service suspension request, SM003: trial extension request)
request_messageStringNRequest Message
KeyTypeDescription
site_idStringSite ID
req_group_idStringRequest ID (PK)
reg_typeStringRequest Type Code
reg_messageStringRequest Message
reg_idStringRegister ID
reg_dtStringRegister Date (UTC +00:00)

This API cancels the request for a change in the service status of the product.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYFixed code of the API (UC011004100)
site_idPathVariableYSITE ID
service_codeStringYService Code (PD001:DRM, PD002:FWM)
request_typeStringYRequest Type Code (SM004:Cancel Service Change Request)
request_group_idStringYRequest ID (PK)
KeyTypeDescription
site_idStringSite ID
req_group_idStringRequest ID (PK)
reg_typeStringExisting Request Type Code
reg_statusStringRequest Status Code (ST001: Request, ST002: Cancel, ST003:Approve)
reg_messageStringRequest Message
reg_idStringRegister ID
reg_dtStringRegister Date (UTC +00:00)
update_dtStringUpdate Date (UTC +00:00)

These APIs are for retrieving DRM-related data.

This API retrieves the list of each DRM license that was responded in a certain period.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYAPI code value (UA003001100)
site_idStringYThe Site ID value shown on DoveRunner Console
fromStringNStart date of the search (YYYY-MM-DD)
toStringNEnd date of the search (YYYY-MM-DD)
search_statusStringNLicense issuance status (success or fail)
search_conditionStringNSearch category (cid, drm_type, user_id, device_id, device_model)
search_keywordStringNThe keyword for category search (valid when search_condition is set)
page_unitIntNNumber of search result (default:25, max: 1000)
page_indexIntNIndex of result page when the results are more than page_unit
  • Request Sample
curl -H 'authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJQYWxseUNvbkFQSSIsImF1ZCI6IklOS0EiLCJpc3MiOiJQYWxseUNvbiIsImFkbWluIjp0cnVlLCJ1c2VySWQiOiJ0ZXN0dXNlciJ9.p7VJmRryoaSVU2qn9PDuoDRIFxphw0N2786bR6zhELQ' 'https://service.pallycon.com/api/v2/drm/license?api_code=UA003001100&site_id=DEMO&from=2020-03-01&to=2020-03-02&search_status=success&search_condition=cid&search_keyword=test'
KeyTypeDescription
cidStringUnique content ID
statusStringLicense issuance status (success, fail)
error_codeStringError code (0000 for successful license issuance)
drm_typeStringType of DRM (PlayReady, Widevine, FairPlay, NCG)
user_idStringUnique ID of end user
device_idStringUnique ID of client device
device_modelStringDevice model name
license_typeStringType of DRM license integration (token, gateway)
platform_nameStringClient platform name
reg_timeStringDatetime of the license request
  • Response Sample
{
"_links":{
"self":{
"href":"http://service.pallycon.com/api/v2/drm/license"
}
},
"error_code":"0000",
"data":[{
"cid":"configtest",
"status":"success",
"error_code":"0000",
"drm_type":"FairPlay",
"user_id":"uuu",
"device_id":"13406080a61bef63aaa1d99a32f51e31c804e659",
"device_model":"iOS-device",
"license_type":"gateway",
"platform_name":"iOS",
"reg_time":"20200302235959"
},
{
"cid":"configtest",
"status":"success",
"error_code":"0000",
"drm_type":"FairPlay",
"user_id":"uuu",
"device_id":"13406080a61bef63aaa1d99a32f51e31c804e659",
"device_model":"iOS-device",
"license_type":"gateway",
"platform_name":"iOS",
"reg_time":"20200302235956"
}],
"count":2
}
}

This API retrieves the list of end user ID that acquired license in a certain period.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYFixed code of the API (UA003001100)
site_idStringYThe Site ID value shown on DoveRunner Console
fromStringNStart date of the search (YYYY-MM-DD)
toStringNEnd date of the search (YYYY-MM-DD)
search_keywordStringNThe user ID to search
page_unitIntNNumber of search result (default:25, max: 1000)
page_indexIntNIndex of result page when the results are more than page_unit
  • Request Sample
curl -H 'authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJQYWxseUNvbkFQSSIsImF1ZCI6IklOS0EiLCJpc3MiOiJQYWxseUNvbiIsImFkbWluIjp0cnVlLCJ1c2VySWQiOiJ0ZXN0dXNlciJ9.p7VJmRryoaSVU2qn9PDuoDRIFxphw0N2786bR6zhELQ' 'https://service.pallycon.com/api/v2/drm/user?api_code=UA003001100&site_id=DEMO&from=2020-03-01&to=2020-03-02
KeyTypeDescription
user_idStringUnique ID of end user
license_cntIntNumber of licenses requested by the user
device_cntIntNumber of client devices used by the user
successIntNumber of successful license issuance
failIntNumber of failed license issuance
  • Response Sample
{
"_links":{
"self":{
"href":"http://service.pallycon.com/api/v2/drm/user"
}
},
"error_code":"0000",
"data":[{
"user_id":"ta5uwrsw",
"license_cnt":1,
"device_cnt":1,
"success":1,
"fail":0
},
{
"user_id":"uuu",
"license_cnt":1729,
"device_cnt":1,
"success":1729,
"fail":0
},
{
"user_id":"5xhsdd36",
"license_cnt":1,
"device_cnt":1,
"success":1,
"fail":0
}],
"count":3
}
}

This API retrieves the list of client devices that acquired license in a certain period.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYFixed code of the API (UA003001100)
site_idStringYThe Site ID value shown on DoveRunner Console
fromStringNStart date of the search (YYYY-MM-DD)
toStringNEnd date of the search (YYYY-MM-DD)
search_keywordStringNThe device ID to search
page_unitIntNNumber of search result (default:25, max: 1000)
page_indexIntNIndex of result page when the results are more than page_unit
  • Request Sample
curl -H 'authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJQYWxseUNvbkFQSSIsImF1ZCI6IklOS0EiLCJpc3MiOiJQYWxseUNvbiIsImFkbWluIjp0cnVlLCJ1c2VySWQiOiJ0ZXN0dXNlciJ9.p7VJmRryoaSVU2qn9PDuoDRIFxphw0N2786bR6zhELQ' 'https://service.pallycon.com/api/v2/drm/device?api_code=UA003001100&site_id=DEMO&from=2020-03-01&to=2020-03-02
KeyTypeDescription
device_idStringUnique ID of client device
device_modelStringClient device model
license_cntIntNumber of licenses requested from the device
successIntNumber of successful license issuance
failIntNumber of failed license issuance
  • Response Sample
{
"_links":{
"self":{
"href":"http://service.pallycon.com/api/v2/drm/device"
}
},
"error_code":"0000",
"data":[{
"device_id":"ea2e698d95b28441422f4997d6ffd5450a",
"device_model":"ChromeCDM-Windows-2",
"license_cnt":1732,
"success":1732,
"fail":0
},
{
"device_id":"13406080a61bef63aaa1d99a32f51e31c804e659",
"device_model":"iOS-device",
"license_cnt":1729,
"success":1729,
"fail":0
},
{
"device_id":"ab3dd736cd46607abbd81ec942e07a620a",
"device_model":"ChromeCDM-Mac-2",
"license_cnt":1,
"success":1,
"fail":0
},
{
"device_id":"d838f619-69e0-4e3a-9b48-5a1b52ce287a",
"device_model":"playready-device",
"license_cnt":1728,
"success":1728,
"fail":0
}],
"count":4
}

This API retrieves the number of licenses issued for each CID(content ID) in a certain period.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYFixed code of the API (UA003001100)
site_idStringYThe Site ID value shown on DoveRunner Console
fromStringNStart date of the search (YYYY-MM-DD)
toStringNEnd date of the search (YYYY-MM-DD)
search_statusStringNLicense issuance status (success or fail)
page_unitIntNNumber of search result (default:25, max: 1000)
page_indexIntNIndex of result page when the results are more than page_unit
  • Request Sample
curl -H 'authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJQYWxseUNvbkFQSSIsImF1ZCI6IklOS0EiLCJpc3MiOiJQYWxseUNvbiIsImFkbWluIjp0cnVlLCJ1c2VySWQiOiJ0ZXN0dXNlciJ9.p7VJmRryoaSVU2qn9PDuoDRIFxphw0N2786bR6zhELQ' 'https://service.pallycon.com/api/v2/drm/cid-drmLicense?api_code=UA003001100&site_id=DEMO&from=2020-03-01&to=2020-03-02
KeyTypeDescription
cidStringUnique ID of content
license_cntIntNumber of licenses issued for the content
  • Response Sample
{
"_links":{
"self":{
"href":"http://service.pallycon.com/api/v2/drm/cid-drmLicense"
}
},
"error_code":"0000",
"data":[
{
"cid":"bigbuckbunny",
"license_cnt":1733
},
{
"cid":"configtest",
"license_cnt":1729
}],
"count":2
}

This API retrieves the number of end users who acquired license for a CID(content ID) in a certain period.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYFixed code of the API (UA003001100)
site_idStringYThe Site ID value shown on DoveRunner Console
cidStringYUnique ID of the content
fromStringNStart date of the search (YYYY-MM-DD)
toStringNEnd date of the search (YYYY-MM-DD)
search_statusStringNLicense issuance status (success or fail)
page_unitIntNNumber of search result (default:25, max: 1000)
page_indexIntNIndex of result page when the results are more than page_unit
  • Request Sample
curl -H 'authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJQYWxseUNvbkFQSSIsImF1ZCI6IklOS0EiLCJpc3MiOiJQYWxseUNvbiIsImFkbWluIjp0cnVlLCJ1c2VySWQiOiJ0ZXN0dXNlciJ9.p7VJmRryoaSVU2qn9PDuoDRIFxphw0N2786bR6zhELQ' 'https://service.pallycon.com/api/v2/drm/cid-user?api_code=UA003001100&site_id=DEMO&cid=bigbuckbunny&from=2020-03-01&to=2020-03-02
KeyTypeDescription
cidStringUnique ID of content
user_idStringUnique ID of end user
license_cntIntNumber of licenses issued for the content
  • Response Sample
{
"_links":{
"self":{
"href":"http://service.pallycon.com/api/v2/drm/cid-user"
}
},
"error_code":"0000",
"data":[{
"cid":"bigbuckbunny",
"user_id":"test-user",
"license_cnt":1728
},
{
"cid":"bigbuckbunny",
"user_id":"rd1z7c08",
"license_cnt":1
}],
"count":2
}

This API retrieves the DRM packaging records in a certain period.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYFixed code of the API (UA003001100)
site_idStringYThe Site ID value shown on DoveRunner Console
fromStringNStart date of the search (YYYY-MM-DD)
toStringNEnd date of the search (YYYY-MM-DD)
search_conditionStringNSearch category (cid, drm_type, user_id, device_id, device_model)
search_keywordStringNThe keyword for category search (valid when search_condition is set)
last_created_time_cidStringNCreation time of the lastly retrieved CID item (for pagination)
last_update_timeStringNUpdate time of the lastly retrieved item (for pagination)

When the last_created_time_cid and last_update_time are set, the response will contain the data that is later than the settings.

KeyTypeDescription
site_idStringSite ID value shown on DoveRunner Console
cidStringUnique ID of the content
trackStringcontent track type (default: HD)
created_timeStringDatetime of the first packaging for the content
update_timeStringDatetime of re-packaging for the content

This API retrieves the information for DRM integration.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
site_idPath VariableYThe Site ID value shown on DoveRunner Console
api_codeStringYFixed code of the API (UA003004100)
KeyTypeDescription
site_idStringSite ID value shown on DoveRunner Console
site_keyStringEncryption key for the service site integration (32 bytes base64 string)
access_keyStringAdditional encryption key for the integration
license_callback_urlStringWebpage URL for callback type license integration (deprecated)
package_callback_urlStringWebpage URL for callback type packager integration (deprecated)
kms_tokenStringSecurity token for KMS integration such as CPIX and SPEKE API
token_durationIntDuration of a license token validity (in seconds)
ivStringSite-specific initial vector (IV) value for DRM encryption

This API updates the information for DRM integration.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
site_idPath VariableYThe Site ID value shown on DoveRunner Console
api_codeStringYFixed code of the API (UA003004100)
license_callback_urlStringNWebpage URL for callback type license integration (deprecated)
package_callback_urlStringNWebpage URL for callback type packager integration (deprecated)
token_durationIntNDuration of a license token validity (in seconds)

This API returns the default response data.

This API registers the FPS certificate to DoveRunner service.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
site_idPath VariableYThe Site ID value shown on DoveRunner Console
api_codeStringYFixed code of the API (UA003004200)
askStringYApplication secret key generated on Apple developer site
key_pwStringYPrivate key password (max 32 bytes)
fps_certblobYFPS certificate file (.der or .cer)
private_keyblobYPrivate key file (.pem)

This API returns the default response data.

This API searches for MAL(Monthly Active License), MAU(Monthly Active Users), and MAD(Monthly Active Devices) for the target date.

ParameterTypeRequiredDescription
AuthorizationHeaderYEncoded JWT data
api_codeStringYFixed code of the API : UA003003100
site_idStringYSite id
target_dateStringYSearch Date (YYYY-MM-DD)
KeyTypeDescription
license_cntIntegerMAL (Monthly Active Licenses)
user_acc_cntIntegerMAU (Monthly Active Users)
device_acc_cntIntegerMAD (Monthly Active Devices)
target_dateIntegerSearch Date