DRM Blacklist Management Guide
Overview
PallyCon Multi-DRM service provides DRM Blacklist Management
feature that allows OTT platforms to block issuance of DRM licenses to users or client devices suspected of piracy or unauthorized content use. Customers can register, view, and update the IDs of users or devices to be blocked via HTTP API or the Blacklist Management section of the PallyCon Console web UI.
sequenceDiagram
participant A as OTT User<br>(Client Device)
participant B as OTT Platform
participant C as PallyCon Server
A ->> C: Request DRM License (Non-blacklisted)
C ->> C: Verify License Token
C ->> A: Issue DRM License
A ->> A: Play Content
opt Blocking via Blacklist
B ->> C: Register illegal user or device ID
C ->> C: Store the ID in Blacklist DB
A ->> C: Request DRM License (Blacklisted)
C ->> C: Verify Token and Check Blacklist
C -->> A: Deny License Issuance
A -->> A: Cannot Play Content
end
The definitions of user ID
and device ID
used in the DRM blacklist feature are as follows
User ID
: The value ofuser_id
in the token data used for DRM license acquisition. If you do not enter this value when creating a token, or enter a random value that is not related to the end user, you cannot apply the blacklist for the user ID.Device ID
: The Device ID value included in the DRM license response data. It can be found on theMulti-DRM
>Licenses
>Active Licenses
screen. The ID may not be unique depending on the client environment, such as browsers.
The device ID is related to the type of DRM supported by the device. If a device supports multiple DRMs, each type of DRM will have a different device ID.
Blacklist Management via Console
You can register, view, and change the status of a blocked user ID or device ID on the Blacklist Management
screen of PallyCon Console.
Managing User Blacklist
After logging in to PallyCon Console, go to Multi DRM
> Blacklist Management
> User Blacklist
menu, and you can manage the blacklist for user ID on the following screen.
![User Blacklist Management](/docs/media/blacklist-user-id-list-en_hu69126b2608d164c0b5f0b38a1a1b0352_114676_a82bc149ab29728638d8b13b6b4cd62a.png)
Looking up blocked users
On the User Blacklist screen, you can apply various search criteria to view the user IDs and current status of blacklisted users.
Registering user IDs to be blocked
Click the Register
button on the User Blacklist screen to go to the Register User ID
screen as shown below.
![Register User ID](/docs/media/blacklist-register-user-id-en_hu6d21a97c0f85a5f935d25e49b61c5904_116342_5db093faad7d6613aee73316bf605246.png)
If you are entering multiple IDs, you can add entries with the +
button above the Register
button, and reduce entries by clicking the trash can button to the right of each entry.
Changing block status
You can change the status (blocked or unblocked) for each blacklisted user ID. By checking the checkbox to the left of the corresponding entry in the list, the Change Status
button will switch to Block
or Unblock
depending on the current status, and clicking it will change the block status of the selected target.
Unblocked
, DRM license issuance will continue as normal as before they were blacklisted.
Managing Device Blacklist
After logging in to PallyCon Console, go to Multi DRM
> Blacklist Management
> Device Blacklist
menu and you can manage the blacklist for device ID on the following screen.
![Device Blacklist Management](/docs/media/blacklist-device-id-list-en_hu9d18cbd3fde095b7f0c085ee769a08a8_128582_75214d764496ff37728cfd40e3464eb6.png)
Looking up blocked devices
On the Device Blacklist screen, you can apply various search criteria to view the device ID, DRM type, and current status of blacklisted devices.
Registering device IDs to be blocked
Click the Register
button on the Device Blacklist screen to go to the Device ID Registration
screen as shown below.
![Register Device ID](/docs/media/blacklist-register-device-id-en_hu14ad9a657cd7f010aac7161adea808e0_36719_351589d2fd321891e1c2035cf133e1bd.png)
For each item you want to register, select the DRM type that corresponds to the device ID and enter the value of the device ID you want to block. If you enter multiple IDs, you can add entries with the +
button above the Register
button, and reduce entries by clicking the trash can button to the right of each entry.
Changing block status
You can change the status (blocked or unblocked) for each blacklisted device ID. By checking the checkbox to the left of the corresponding entry in the list, the Change Status
button will switch to Block
or Unblock
depending on the current status, and clicking it will change the block status of the selected target.
Unblocked
, DRM license issuance will continue as normal as before they were blacklisted.
Blacklist Management via API
In addition to the Console UI, the DRM Blacklist feature can also be managed via HTTP API. If you need an automated integration with your system, please refer to the guide below to implement an API-based integration.
API Basics
PallyCon 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](/docs/media/service-api-jwt-spec_hu4e79bf51f45a9e76549e7aafec4d89cf_111970_cd845a0d3413b8ee5b1ffeb1af027d37.jpeg)
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.
JWT Structure
As shown on the above image, an encoded JWT token has the following format:
base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + HS256 signature value
Payload Specification
The token uses json payload data as below example:
{
"sub" : "PallyConAPI",
"aud" : "INKA",
"iss" : "PallyCon",
"account_id" : "Your PallyCon account ID",
"account_seq": "Your PallyCon account SEQ",
"exp": 1583191411
}
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 PallyCon service |
account_seq | Y | Your PallyCon 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 PallyCon service API.
Common Request Specification
Blacklist APIs commonly require the following request data.
Name | Type | Description |
---|---|---|
Authorization | Header / String | JWT token for API authentication. Added to HTTP headers. |
api_code | URL Param / String | Code to separate APIs by functionality. Added as a URL parameter. |
Common Response Specification
When calling the PallyCon 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 |
Get User ID List
This API retrieves a list of blacklisted user IDs.
- URL: https://service.pallycon.com/api/v2/drm/blacklist/user/{siteId}
- Method: GET
- API Code : UA013001100
Request Data Spec
Parameter | Format | Required | Description |
---|---|---|---|
user_id | String | N | Specific user ID to retrieve the data |
status_code | String | N | Status code (BL000 : Blocked, BL001 : Unblocked) Default: all |
from | String | N | Start date of lookup period (format: YYYY-MM-DD) By date of registration (GMT) |
to | String | N | End date of lookup period (format: YYYY-MM-DD) By date of registration (GMT) |
time_zone | String | N | Set the time zone used for search (format: +/-hh:mm) default: +00:00 |
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 |
- Example Request
GET /api/v2/drm/blacklist/user/{siteId}?api_code=UA013001100&user_id=testUser&from=2024-04-15&to=2024-04-17&page_index=1&page_unit=10&site_id=DEMO&status_code=BL000&time_zone=%2B09%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: service.pallycon.com
Response Data Spec
Name | Type | Description |
---|---|---|
black_list | Json Array | List of user IDs |
user_id | String | User ID registered in the blacklist |
status_code | String | Status code (BL000 : Blocked, BL001 : Unblocked) |
reg_date | String | Registration date (GMT) |
update_date | String | Updated date (GMT) |
- Example Response
{
"black_list" : [
{
"user_id" : "test",
"status_code" : "BL000",
"reg_date" : "20240214000000",
"update_date" : "20240214000000"
},
{
"user_id" : "test",
"status_code" : "BL000",
"reg_date" : "20240214000000",
"update_date" : "20240214000000"
},
],
total_count : 2,
error_code: "0000",
error_message: "Success."
}
Register User ID in Blacklist
This API registers a user ID in the Blacklist.
- URL: https://service.pallycon.com/api/v2/drm/blacklist/user/{siteId}
- Method: POST
- API Code : UA013001200
Request Data Body
{
"user_id_list" : [
"test", "test2"
]
}
Parameter | Format | Required | Description |
---|---|---|---|
user_id_list | String Array | Y | List of user ID to register in Blacklist |
Response Data Format
{
"error_code" : "0000",
"error_message" : "Success"
}
Change Status of User ID
This API changes the block/unblock status of a blacklisted user ID.
- URL: https://service.pallycon.com/api/v2/drm/blacklist/user/{siteId}
- Method: PUT
- API Code : UA013001200
Request Data Body
{
"user_id_list" : [
"test", "test2"
],
"status_code" : "BL000"
}
Parameter | Format | Required | Description |
---|---|---|---|
user_id_list | String Array | Y | List of user ID to update status |
status_code | String | Y | Status to apply (BL000 : Blocked, BL001 : Unblocked) |
Response Data Format
{
"error_code" : "0000",
"error_message" : "Success"
}
Get Device ID List
This API retrieves a list of blacklisted device IDs.
- URL: https://service.pallycon.com/api/v2/drm/blacklist/device/{siteId}
- Method: GET
- API Code : UA013002100
Request Data Spec
Parameter | Format | Required | Description |
---|---|---|---|
device_id | String | N | Device ID to retrieve |
status_code | String | N | Status code (BL000 : Blocked, BL001 : Unblocked) Default: all |
from | String | N | Start date of lookup period (format: YYYY-MM-DD) By date of registration (GMT) |
to | String | N | End date of lookup period (format: YYYY-MM-DD) By date of registration (GMT) |
time_zone | String | N | Set the time zone used for search (format: +/-hh:mm) default: +00:00 |
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 |
- Example Request
GET /api/v2/drm/blacklist/device/{siteId}?api_code=UA013002100&device_id=device1&from=2024-04-15&to=2024-04-17&page_index=1&page_unit=10&site_id=DEMO&status_code=BL000&time_zone=%2B09%3A00&dr HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: service.pallycon.com
Response Data Spec
Name | Format | Description |
---|---|---|
black_list | Json Array | List of retrieved devices |
device_id | String | Device ID registered in blacklist |
drm_type | String | DRM type of the device (widevine / playready / fairplay / ncg) |
status_code | String | Status code (BL000 : Blocked, BL001 : Unblocked) |
reg_date | String | Registration date (GMT) |
update_date | String | Updated date (GMT) |
- Example Response
{
"black_list" : [
{
"device_id" : "59fe7cf3e07c42e8a5de64fefb1356bd",
"drm_type" : "widevine",
"status_code" : "BL000",
"reg_date" : "20240214000000",
"update_date" : "20240214000000"
},
{
"device_id" : "59fe7cf3e07c42e8a5de64fefb1356bd",
"drm_type" : "widevine"
"status_code" : "BL000",
"reg_date" : "20240214000000",
"update_date" : "20240214000000"
},
],
total_count : 2,
error_code: "0000",
error_message: "Success."
}
Register Device ID in Blacklist
This API registers device ID(s) in the blacklist.
- URL: https://service.pallycon.com/api/v2/drm/blacklist/device/{siteId}
- Method: POST
- API Code : UA013002200
Request Data Body
{
"device_id_list": [
{
"device_id": "59fe7cf3e07c42e8a5de64fefb1356bd",
"drm_type": "widevine"
},
{
"device_id": "59fe7cf3e07c42e8a5de6",
"drm_type": "playready"
}
]
}
Parameter | Format | Required | Description |
---|---|---|---|
device_id | String | Y | Device ID to register in Blacklist |
drm_type | String | Y | DRM type of the device (playready / widevine / fairplay / ncg) |
Response Data Format
{
"error_code" : "0000",
"error_message" : "Success"
}
Update Status of Device ID
This API changes the block/unblock status of blacklisted device ID(s).
- URL: https://service.pallycon.com/api/v2/drm/blacklist/device/{siteId}
- Method: PUT
- API Code : UA013002200
Request Data Body
{
"device_id_list": [
{
"device_id": "59fe7cf3e07c42e8a5de64fefb1356bd",
"drm_type": "widevine"
},
{
"device_id": "59fe7cf3e07c42e8a5de6",
"drm_type": "playready"
}
],
"status_code": "BL000"
}
Parameter | Format | Required | Description |
---|---|---|---|
device_id_list | Json Array | Y | List of device ID to update status |
device_id | String | Y | Device ID to change status |
drm_type | String | Y | DRM type of the device (playready / widevine / fairplay / ncg) |
status_code | String | Y | Status to apply (BL000 : Blocked, BL001 : Unblocked) |
Response Data Format
{
"error_code" : "0000",
"error_message" : "Success"
}
Error Codes
Error Code | Message |
---|---|
A9048 | Fail to Insert User IDs In Black List. |
A9049 | Request Spec About Black List API Is Invalid. |
A9050 | User ID Already Exists In Black List. |
A9051 | Fail to Get User IDs From Black List. |
A9052 | Fail to Delete User IDs In Black List. |
A9053 | Fail to Insert Device IDs In Black List. |
A9054 | Device ID Already Exists In Black List. |
A9055 | Fail to Get Device IDs From Black List. |
A9056 | Fail to Delete Device IDs In Black List. |