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.
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:
base64UrlEncode(header ) + " . " + base64UrlEncode( payload ) + " . " + HS256 signature value
The token uses json payload data as below example:
"account_id" : " Your DoveRunner account ID " ,
"account_seq" : " Your DoveRunner account SEQ " ,
Key Required Value sub Y Fixed value as PallyConAPI
aud Y Fixed value as INKA
iss Y Fixed value as PallyCon
account_id Y Your account ID of DoveRunner service account_seq Y Your DoveRunner account’s SEQ
(can be requested via Helpdesk ticket) exp N Expiration 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 Code Description 401 JWT Token specification is incorrect or the user information cannot be found 403 Do not have permission for the called API 200 HTTP communication success
When the HTTP status code is 200
(HTTP communication success), you’ll get the below response data in JSON format.
Key Type Value error_code String 0000: Success / other numbers: failure error_message String Shows the error message on failed request data JSON Result of the successful API request
These APIs are for managing DoveRunner service account and sites.
Note
A site
in DoveRunner service means a service site of our customer where DoveRunner solution is applied. A DoveRunner account has one site
by default, and additional sites can be added to an account if needed. (e.g. a reseller account with multiple customers)
A site has a unique ID as four alphanumeric characters.
This API retrieves the list of sites under the DoveRunner account.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y Fixed API code as UC011004100
Key Type Description site_id String Unique ID of the site (four alphanumeric characters) service_name String Name of the service site product_list Array Product List product_list.[].service_code String Service code ( PD001 : DRM, PD002 : FWM ) product_list.[].status_code String Service Status (SE000 : In service, SE001 : Suspended )
This API requests additional service site for the account. (in case of multiple service sites in an account)
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y API code value as UA010310200
service_name String Y Name of the additional service site
Key Type Description seq Int Sequence number of the request
This API returns the status of request for additional service site.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y API code value as UA010310100
from String N Start date of the search (YYYY-MM-DD) to String N End date of the search (YYYY-MM-DD) req_status String N Status of the request search_type String N Type of the search (account_id, site_id) search_keyword String N Keyword for the search (used when search_type is set) page_unit Int N Number of search result (default:25, max: 1000) page_index Int N Index of result page when the results are more than page_unit
Key Type Description seq Int Sequence number of the request account_id String ID of the service account site_id String ID of the service site service_name String Name of the service site status String Status of the additional site request update_time String Datetime of the status update reg_time String Datetime of the request registration
This API returns the list of sub-members in an account.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y API code value as UA010700200
page_unit Int N Number of search result (default:25, max: 1000) page_index Int N Index of result page when the results are more than page_unit
Key Type Description group_name String The sub-member’s group name group_seq Int Sequence number of the group (refer to the below table) member_seq Int Sequence number of the sub-member member_email String Email address of the sub-member status_code String Status code (MT001: active member, MT002: inactive) reg_date String Date 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.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y API code value as UA010700200
member_email String Y Email address of the sub-member group_seq Int N Sequence number of a member group to set
Key Type Description member_seq Int Sequence number of the sub-member
This API resets password of a sub-member.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y API code value as UA010700200
member_seq Int Y Sequence 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.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y API code value as UA010700200
member_seq Int Y Sequence number of the sub-member member_status String N Status code to apply (MT001: active, MT002: inactive) group_seq Int N Sequence 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.
This API returns the status of service status change request. (for the latest request)
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y Fixed code of the API (UC011004100) site_id PathVariable Y SITE ID service_code String Y Service Code (PD001:DRM, PD002:FWM)
Key Type Description site_id String Site ID req_group_id String Request ID (PK) reg_type String Request Type Code reg_message String Request Message reg_status String Request Status (ST001: Request, ST002: Cancel, ST003:Approve) reg_id String Register ID reg_dt String Register Date (UTC +00:00 기준) update_dt String Update Date (UTC +00:00 기준)
This API registers requests to change the status of product services.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y Fixed code of the API (UC011004100) site_id PathVariable Y SITE ID service_code String Y Service Code (PD001:DRM, PD002:FWM) request_type String Y Request Type Code (SM001: service resume request, SM002: service suspension request, SM003: trial extension request) request_message String N Request Message
Key Type Description site_id String Site ID req_group_id String Request ID (PK) reg_type String Request Type Code reg_message String Request Message reg_id String Register ID reg_dt String Register Date (UTC +00:00)
This API cancels the request for a change in the service status of the product.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y Fixed code of the API (UC011004100) site_id PathVariable Y SITE ID service_code String Y Service Code (PD001:DRM, PD002:FWM) request_type String Y Request Type Code (SM004:Cancel Service Change Request) request_group_id String Y Request ID (PK)
Key Type Description site_id String Site ID req_group_id String Request ID (PK) reg_type String Existing Request Type Code reg_status String Request Status Code (ST001: Request, ST002: Cancel, ST003:Approve) reg_message String Request Message reg_id String Register ID reg_dt String Register Date (UTC +00:00) update_dt String Update 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.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y API code value (UA003001100) site_id String Y The Site ID
value shown on DoveRunner Console from String N Start date of the search (YYYY-MM-DD) to String N End date of the search (YYYY-MM-DD) search_status String N License issuance status (success or fail) search_condition String N Search category (cid, drm_type, user_id, device_id, device_model) search_keyword String N The keyword for category search (valid when search_condition is set) page_unit Int N Number of search result (default:25, max: 1000) page_index Int N Index of result page when the results are more than page_unit
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'
Key Type Description cid String Unique content ID status String License issuance status (success, fail) error_code String Error code (0000 for successful license issuance) drm_type String Type of DRM (PlayReady, Widevine, FairPlay, NCG) user_id String Unique ID of end user device_id String Unique ID of client device device_model String Device model name license_type String Type of DRM license integration (token, gateway) platform_name String Client platform name reg_time String Datetime of the license request
"href" : " http://service.pallycon.com/api/v2/drm/license "
"device_id" : " 13406080a61bef63aaa1d99a32f51e31c804e659 " ,
"device_model" : " iOS-device " ,
"license_type" : " gateway " ,
"reg_time" : " 20200302235959 "
"device_id" : " 13406080a61bef63aaa1d99a32f51e31c804e659 " ,
"device_model" : " iOS-device " ,
"license_type" : " gateway " ,
"reg_time" : " 20200302235956 "
This API retrieves the list of end user ID that acquired license in a certain period.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y Fixed code of the API (UA003001100) site_id String Y The Site ID
value shown on DoveRunner Console from String N Start date of the search (YYYY-MM-DD) to String N End date of the search (YYYY-MM-DD) search_keyword String N The user ID to search page_unit Int N Number of search result (default:25, max: 1000) page_index Int N Index of result page when the results are more than page_unit
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
Key Type Description user_id String Unique ID of end user license_cnt Int Number of licenses requested by the user device_cnt Int Number of client devices used by the user success Int Number of successful license issuance fail Int Number of failed license issuance
"href" : " http://service.pallycon.com/api/v2/drm/user "
This API retrieves the list of client devices that acquired license in a certain period.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y Fixed code of the API (UA003001100) site_id String Y The Site ID
value shown on DoveRunner Console from String N Start date of the search (YYYY-MM-DD) to String N End date of the search (YYYY-MM-DD) search_keyword String N The device ID to search page_unit Int N Number of search result (default:25, max: 1000) page_index Int N Index of result page when the results are more than page_unit
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
Key Type Description device_id String Unique ID of client device device_model String Client device model license_cnt Int Number of licenses requested from the device success Int Number of successful license issuance fail Int Number of failed license issuance
"href" : " http://service.pallycon.com/api/v2/drm/device "
"device_id" : " ea2e698d95b28441422f4997d6ffd5450a " ,
"device_model" : " ChromeCDM-Windows-2 " ,
"device_id" : " 13406080a61bef63aaa1d99a32f51e31c804e659 " ,
"device_model" : " iOS-device " ,
"device_id" : " ab3dd736cd46607abbd81ec942e07a620a " ,
"device_model" : " ChromeCDM-Mac-2 " ,
"device_id" : " d838f619-69e0-4e3a-9b48-5a1b52ce287a " ,
"device_model" : " playready-device " ,
This API retrieves the number of licenses issued for each CID(content ID) in a certain period.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y Fixed code of the API (UA003001100) site_id String Y The Site ID
value shown on DoveRunner Console from String N Start date of the search (YYYY-MM-DD) to String N End date of the search (YYYY-MM-DD) search_status String N License issuance status (success or fail) page_unit Int N Number of search result (default:25, max: 1000) page_index Int N Index of result page when the results are more than page_unit
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
Key Type Description cid String Unique ID of content license_cnt Int Number of licenses issued for the content
"href" : " http://service.pallycon.com/api/v2/drm/cid-drmLicense "
This API retrieves the number of end users who acquired license for a CID(content ID) in a certain period.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y Fixed code of the API (UA003001100) site_id String Y The Site ID
value shown on DoveRunner Console cid String Y Unique ID of the content from String N Start date of the search (YYYY-MM-DD) to String N End date of the search (YYYY-MM-DD) search_status String N License issuance status (success or fail) page_unit Int N Number of search result (default:25, max: 1000) page_index Int N Index of result page when the results are more than page_unit
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
Key Type Description cid String Unique ID of content user_id String Unique ID of end user license_cnt Int Number of licenses issued for the content
"href" : " http://service.pallycon.com/api/v2/drm/cid-user "
This API retrieves the DRM packaging records in a certain period.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y Fixed code of the API (UA003001100) site_id String Y The Site ID
value shown on DoveRunner Console from String N Start date of the search (YYYY-MM-DD) to String N End date of the search (YYYY-MM-DD) search_condition String N Search category (cid, drm_type, user_id, device_id, device_model) search_keyword String N The keyword for category search (valid when search_condition is set) last_created_time_cid String N Creation time of the lastly retrieved CID item (for pagination) last_update_time String N Update 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.
Key Type Description site_id String Site ID
value shown on DoveRunner Consolecid String Unique ID of the content track String content track type (default: HD) created_time String Datetime of the first packaging for the content update_time String Datetime of re-packaging for the content
This API retrieves the information for DRM integration.
Parameter Type Required Description Authorization Header Y Encoded JWT data site_id Path Variable Y The Site ID
value shown on DoveRunner Console api_code String Y Fixed code of the API (UA003004100)
Key Type Description site_id String Site ID
value shown on DoveRunner Consolesite_key String Encryption key for the service site integration (32 bytes base64 string) access_key String Additional encryption key for the integration license_callback_url String Webpage URL for callback type license integration (deprecated) package_callback_url String Webpage URL for callback type packager integration (deprecated) kms_token String Security token for KMS integration such as CPIX and SPEKE API token_duration Int Duration of a license token validity (in seconds) iv String Site-specific initial vector (IV) value for DRM encryption
This API updates the information for DRM integration.
Parameter Type Required Description Authorization Header Y Encoded JWT data site_id Path Variable Y The Site ID
value shown on DoveRunner Console api_code String Y Fixed code of the API (UA003004100) license_callback_url String N Webpage URL for callback type license integration (deprecated) package_callback_url String N Webpage URL for callback type packager integration (deprecated) token_duration Int N Duration of a license token validity (in seconds)
This API returns the default response data.
This API registers the FPS certificate to DoveRunner service.
Parameter Type Required Description Authorization Header Y Encoded JWT data site_id Path Variable Y The Site ID
value shown on DoveRunner Console api_code String Y Fixed code of the API (UA003004200) ask String Y Application secret key generated on Apple developer site key_pw String Y Private key password (max 32 bytes) fps_cert blob Y FPS certificate file (.der or .cer) private_key blob Y Private 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.
Note
For MAD, you need to set persistentStateRequired
in the player to generate a unique ID per PC for the desktop Chrome browser (see HTML Player sample source ).
Without this setting, the same ID will be applied to the Chrome browser on all PCs and reflected in MAD as one device.
Parameter Type Required Description Authorization Header Y Encoded JWT data api_code String Y Fixed code of the API : UA003003100 site_id String Y Site id target_date String Y Search Date (YYYY-MM-DD)
Key Type Description license_cnt Integer MAL (Monthly Active Licenses) user_acc_cnt Integer MAU (Monthly Active Users) device_acc_cnt Integer MAD (Monthly Active Devices) target_date Integer Search Date