Implementing Device Limits

Introduction

Brightcove's Playback Rights Management Service allows you to set device limits for video playback. Each user's device is registered with a unique id when a DRM license request is made. You control the number of devices per user.

The device limit is checked and enforced with each license request. To use this restriction, you will pass a JSON Web Token (JWT) with the current user id uid to the Playback API.

If you are not familiar with this feature, see the Overview: Playback Rights Management Service document.

Device registration

A device is registered with Brightcove when a valid playback request which includes a JSON Web Token (JWT) with uid and dlimit claims is received. From that moment, this device will occupy one slot.

Implementation

To enable device limits, follow these steps:

1. Create a JSON Web Token (JWT) with the generally required claims along with the uid and dlimit claims.

   Each user's device is registered with a unique id when a DRM license request is made.

   The dlimit claim lets you control how many devices can be associated with the specified user uid. The value must be > 0.

   If the dlimit claim value is dropped in later requests, previously allowed devices will continue to operate.

   Example
   If the dlimit value is set to 3, the user can play on devices A, B, & C (all would be allowed). Trying to play on device D would be denied.
   If the dlimit value is changed to 1, the user can still play on all 3 devices A, B, & C, unless the devices are manually revoked by managing devices with the Devices API. To do this, see the Manage devices section.

2. Manage user devices with the Devices API. This API allows you to get the devices for a user, delete devices and update the name for a device.

   When a device is registered, it is identified by id and nickname. The Devices API lets you edit the device nickname, making it easy to manage your list of devices.

3. Configure your player to use the JSON Web Token (JWT) created in the previous step.

Manage devices

You can manage user devices with the Devices API.

Devices API

With the Devices API, you can get and delete user devices.

Base URL

The base URL for the API is:

https://playback-auth.api.brightcove.com/v1

Account path

In all cases, requests will be made for a specific Video Cloud Account. So, you will always add the term accounts followed by your account id to the base URL:

https://playback-auth.api.brightcove.com/v1/accounts/{accountID}

Authorization

An access token for requests is required and must be present in the Authorization header:

Authorization: Bearer {access_token}

The access token is a temporary OAuth2 access token that must be obtained from the Brightcove OAuth service. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.

Permissions

Requests to the Devices API must be made from client credentials with the following permissions:

• video-cloud/playback-auth/devices/read
• video-cloud/playback-auth/devices/write

API methods

The Devices API supports the following requests. For details, see the Devices API Reference.

Get all user devices

GET /v1/accounts/{accountID}/users/{userID}/devices

Response body

The response body contains an array of devices, and should look similar to this:

[
    {
        "id": "12e12345-11e1-1bd1-d123-1234567890",
        "created_at": 1612646018,
        "updated_at": 1612646018,
        "name": "my device1",
        "user_agent": "PlayReadyClient"
    },
    {
        "id": "WVCf123456789abcdefghijkl1234567890abcdefg",
        "created_at": 1612385697,
        "updated_at": 1612385697,
        "name": "my device2",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:85.0) Gecko/20100101 Firefox/85.0"
    }
]

Update device name

The PATCH request lets you set a descriptive name for the device.

PATCH  /v1/accounts/{accountID}/users/{userID}/devices/{deviceID}
  Content-Type: application/json
  Body: {devices object}

Request body

The request body contains the device name.

{
    "name": "my device1"
}

Here are the field details:

Delete all user devices

DELETE /v1/accounts/{accountID}/users/{userID}/devices

Delete a specific user device

DELETE /v1/accounts/{accountID}/users/{userID}/devices/{deviceID}