---
title: "DRM Blacklist Management Guide"
description: "This document explains how to use the DRM blacklist feature to block the issuance of licenses to users or client devices suspected of illegal use of your service."
---
> For the complete documentation index, see [llms.txt](/llms.txt).

DoveRunner 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 DoveRunner Console web UI.

```mermaid
sequenceDiagram
    participant A as OTT User<br/>(Client Device)
    participant B as OTT Platform
    participant C as DoveRunner 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
```

:::note 

The definitions of `user ID` and `device ID` used in the DRM blacklist feature are as follows 
- `User ID`: The value of `user_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 the `Multi-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 DoveRunner Console.

### Managing User Blacklist

After logging in to DoveRunner 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](/img/content-security/blacklist-user-id-list-en.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](/img/content-security/blacklist-register-user-id-en.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.

:::note 

For user IDs that are switched to `Unblocked`, DRM license issuance will continue as normal as before they were blacklisted. 

:::

### Managing Device Blacklist

After logging in to DoveRunner 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](/img/content-security/blacklist-device-id-list-en.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](/img/content-security/blacklist-register-device-id-en.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.

:::note 

For device IDs that are switched to `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

`DoveRunner Service API` uses [JSON Web Token(JWT)](https://jwt.io/introduction/) for secure transmission of information.

> You can create and test the token using an [online JWT tool](https://jwt.io/#libraries) or a server-side programming language.

![Service API JWT Specification](/img/content-security/service-api-jwt-spec.jpeg)

The token should be signed using an account-specific secret key with HMAC SHA256(HS256) algorithm. Please create a ticket on [Helpdesk](https://support.doverunner.com/) 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:

```txt
base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + HS256 signature value
```

#### Payload Specification

The token uses json payload data as below example:

```json
{
    "sub" : "PallyConAPI",
    "aud" : "INKA",
    "iss" : "PallyCon",
    "account_id" : "Your DoveRunner account ID",
    "account_seq": "Your DoveRunner 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 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.

#### 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 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 |

### Get User ID List

This API retrieves a list of blacklisted user IDs.

- URL: `https://service.doverunner.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

```txt
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.doverunner.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

```json
{
  "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.doverunner.com/api/v2/drm/blacklist/user/{siteId}`
- Method: POST
- API Code : UA013001200

#### Request Data Body

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

```json
{
	"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.doverunner.com/api/v2/drm/blacklist/user/{siteId}`
- Method: PUT
- API Code : UA013001200

#### Request Data Body

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

```json
{
	"error_code" : "0000",
	"error_message" : "Success"
}
```

### Get Device ID List

This API retrieves a list of blacklisted device IDs.

- URL: `https://service.doverunner.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

```txt
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.doverunner.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

```json
{
  "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.doverunner.com/api/v2/drm/blacklist/device/{siteId}`
- Method: POST
- API Code : UA013002200

#### Request Data Body

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

```json
{
	"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.doverunner.com/api/v2/drm/blacklist/device/{siteId}`
- Method: PUT
- API Code : UA013002200

#### Request Data Body

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

```json
{
	"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. |