Implementing Device Limits

Introduction

With Brightcove Playback Restrictions, you can 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 new to this feature, see the Overview: Brightcove Playback Restrictions 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.

JWT claims

For device limits, you can use the following claims along with the generally required claims:

• uid:

  The user id of the end viewer. This field is required for device registration.

• dlimit:

  For DRM content, the dlimit claim indicates how many devices a user can stream. Every device from each user requesting a stream is registered. Once the stream limit is reached, no more devices will be able to stream.

  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.

Implementation

To use 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.

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 all of the devices for the specified account and user.

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

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"
    }
]

Get all account devices

Get all of the devices for each user within an account. You will use the page and per_page parameters to limit the response.

GET /v1/accounts/{accountID}/devices?page=0&per_page=10

Parameters:

The response body contains an array of users and devices:

{
  "metadata": 
  {
    "page": 3,
    "per_page": 10,
    "page_count": 5,
    "total_count": 55,
    "Links": [
      {"self": "/v1/accounts/123456/devices?page=3&per_page=10"},
      {"first": "/v1/accounts/123456/devices?page=0&per_page=10"},
      {"previous": "/v1/accounts/123456/devices?page=2&per_page=10"},
      {"next": "/v1/accounts/123456/devices?page=4&per_page=10"},
      {"last": "/v1/accounts/123456/devices?page=4&per_page=10"}
    ]
  },
  "records": [
    {
      "account_id": "123456",
      "user_id": "user_1",
      "device": "device_1"
    },
    {
      "account_id": "123456",
      "user_id": "user_1",
      "device": "device_2"
    },
    ...
    {
      "account_id": "123456",
      "user_id": "user_10",
      "device": "device_1"
    }
  ]
}

Update device name

Update the device name for the specified account, user and device.

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}

The request body contains the device name.

{
    "name": "my device1"
}

Here are the field details:

Delete all user devices

Delete all of the devices associated with a user.

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

Delete a specific user device

Delete a specific device for a user.

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