Implementing Playback Rights

Introduction

Brightcove's Playback Rights Management Service provides a scalable and expressive way to manage video playback.

If you are not familiar with this feature, see the Overview: Brightcove Playback Restrictions document.

Validation process

Playback Rights are applied in order of specificity and matching. An allow rule negates the rest of the rules since they are less specific than the one allowing the rule.

You may want to allow a specific ip to avoid a country rule for that ip. You may also want to block a different ip that would normally be allowed by the country restriction. So, it can make sense to have both block-ips and allow-ips in the same playback rights definition. The same holds true for other rules.

You can have allow and block rules for most rights. Countries is the only one where it might not make sense to have both.

The following flow diagrams show how the validation process works:

Geographic checks
Schedule check
Proxy check
Domain check

Geographic checks

The flow for geographic restrictions will follow one of the following diagrams, based on the value of the geo_global_rule field:

geo_global_rule is set to allow_all
geo_global_rule is set to block_all
geo_global_rule is set to null

If the geographic checks pass, then continue with the additional checks in the next diagram.

Additional validation checks

If the geographic checks pass, then the following checks are processed in order:

Schedule check
Proxy check
Domain check

How does it work?

Playback Rights is one part of the Playback Restrictions solution.

Playback Rights

By default, the player (Brightcove Player and the Native SDKs) makes a request to the Playback API if it has a policy key. The player sends the request to the following endpoint, and retrieves your content:

edge.api.brightcove.com

To check Playback Rights with your Playback API request, you will not include the Policy Key. When there is no Policy Key, the player sends the request to this endpoint:

edge-auth.api.brightcove.com

If all of the Playback Rights validation checks pass, then your content is returned.

Workflow

To manage playback restrictions, follow these steps:

Set up your account
Define restrictions
Associate restrictions with a video
Configure your player

Set up your account

This feature is available for a specific set of customers with access to the Limited Availability phase of the Playback Rights Management Service. Contact your Customer Success Manager for details.

Generate OAuth credentials

Get your BC_TOKEN and account number.

Log into Video Cloud Studio. In the Admin dropdown, select Account Information. Copy your Account ID.

With any page in Studio open, open the developer tools for the browser, go to the Console, and paste in the following code:

var cookiesArray =
            document.cookie.split(";"), cookiesObj = {}, i, tmpArray = [];
            for (i = 0; i < cookiesArray.length; i++) {
            tmpArray = cookiesArray[i].split("=");
            if (tmpArray[0].indexOf('BC_TOKEN') > -1) {
            cookiesObj.BC_TOKEN = tmpArray[1];
            }
            }
            window.prompt("BC_TOKEN:", cookiesObj.BC_TOKEN);

and press return.

You should see a prompt appear that contains your BC_TOKEN

Request client credentials

Add account permissions for the Playback Rights API.

The simplest way to create client credentials for the Playback Rights API is to use this online app and ensure that you include these permissions when you create the credentials:

Playback Rights Permissions
If you prefer generating your credentials using the OAuth API directly, continue with the following steps.

Here is an example of an OAuth client request with the permissions needed. See Getting your BC_TOKEN for information on getting your BC_TOKEN.

curl \
            --include \
            --header "Authorization: BC_TOKEN your BC_TOKEN" \
            --data {
            name="demo",
            maximum_scope=[{
            "identity": {
            "type": "video-cloud-account",
            "account-id": your account id
            },
            "operations": [
            "video-cloud/playback-auth/playback-rights/read",
            "video-cloud/playback-auth/playback-rights/write",
            "video-cloud/video/read",
            "video-cloud/video/create",
            "video-cloud/video/update",
            "video-cloud/video/delete",
            "video-cloud/playback-auth/key/read",
            "video-cloud/playback-auth/key/write"
            ]
            }]
            } \
            https://oauth.brightcove.com/v4/client_credentials

From the API response, copy the client_id and client_secret. You will use these to generate an access token when making requests to the Playback Rights API.

Define restrictions

Use the Playback Rights API to define video playback restrictions.

Playback Rights API

Each playback rights restriction object can be used with one or more videos.

Base URL

The base URL for the API is:

https://playback-rights.api.brightcove.com

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-rights.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 Playback Rights API must be made from client credentials with the following permissions:

video-cloud/playback-auth/playback-rights/read
video-cloud/playback-auth/playback-rights/write

Manage restrictions

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

Create new playback rights

POST /v1/accounts/{accountID}/playback_rights
        Content-Type: application/json
        Body: {playback rights object}

For a list of valid fields, see the Request body section.

Curl example

Create playback right valid only for Australia.

curl -X POST \
          https://playback-rights.api.brightcove.com/v1/accounts/{your_account_id}/playback_rights \
          -H 'Authorization: Bearer {access_token}' \
          -H 'Content-Type: application/json' \
          -d '{
          "geo": {
          "allowed_countries": [
          "AU"
          ]
          }
          }'

API Response

Save the playback_rights_id value for later use. You can find this value in the API response. Either:

Response header:

The playback_rights_id value can be found in the Location field of the Header response. It should be similar to this:
```
Location: /v1/accounts/your
              account_id/playback_rights/your playback_rights_id
          
```

Response body

The playback_rights_id value can be found in the response body as the id field. It should be similar to this:

{
            "id": "your playback_rights_id",
            "geo": {
            "allowed_countries": [
            "MX",
            "US"]
            }

Get all playback rights for an account

GET /v1/accounts/{accountID}/playback_rights

Get a specific playback right for an account

GET
        /v1/accounts/{accountID}/playback_rights/{playbackRightsID}

Update a specific playback right:

PUT
        /v1/accounts/{accountID}/playback_rights/{playbackRightsID}
        Content-Type: application/json
        Body: {playback rights object}

For a list of valid fields, see the Request body section.

Delete a specific playback right:

DELETE
        /v1/accounts/{accountID}/playback_rights/{playbackRightsID}

Request body

Here is an example of all of the fields you can include in the request body:

{
        "geo": {
        "allowed_countries": [
        "MX",
        "US"
        ],
        "blocked_countries": [
        "JP",
        "CN"
        ],
        "allowed_zip_codes": [
        "US-90210"
        ],
        "blocked_zip_codes": [
        "US-72810"
        ],
        "allowed_dmas": [
        501
        ],
        "blocked_dmas": [
        803
        ]
        },
        "blocked_proxies": {
        "anonymous": true,
        "public": true,
        "corporate": true,
        "transparent": true,
        "hosting": true
        },
        "allowed_domains": [
        "www.google.com",
        "www.brightcove.com"
        ],
        "blocked_domains": [
        "www.ooyala.com"
        ],
        "start_time": 1572905011,
        "end_time": 1672905011,
        "allowed_ips": [
        "192.168.1.1"
        ],
        "blocked_ips": [
        "192.168.1.1"
        ],
        "allowed_days": [
        "mon",
        "tue"
        ],
        "allowed_hours": [
        "5-6"
        ],
        "allow_insecure": true,
        "disabled": false,
        "geo_global_rule": "allow_all",
        "is_default": true,
        "name": "Optional playback right name"
        }

Playback Rights API fields

Field	Type	Description
`allowed_days`	String	Array of 3-letter lowercase names for the days that the resource is allowed to be retrieved. One or more of: `mon, tue, wed, thu, fri, sat, sun`
`allowed_domains`, `blocked_domains`	String	Array of domain names
`allowed_hours`	Integer	Array of hours from the 24-hour clock (starting at 0 and up to 47) during which the resource is allowed to be retrieved. 0 to 23 for current day, and 24 to 47 for next day end-date. If an allowed hours block starts in previous day and ends at the following day then a 24+ notation is required. Example: the value of `3-4` in this header means that the resource is available from 3:00 am UTC to 3:59 am UTC
`allow_insecure`	Boolean	Default: `false` Setting this to `true` makes the JWT token optional.
`allowed_ips`, `blocked_ips`	Integer	Array of ipv4/ipv6 addresses or CIDR blocks.
`disabled`	Boolean	Default: `false` Setting this to `true` disables the Playback Right, allowing playback for everyone.
`geo`	Object	Properties related to geographic rights
`geo.allowed_countries`, `geo.blocked_countries`	String	Array of two letter country codes, which follow the ISO 3166-1 alpha-2 standard. For a list of values, see the Officially assigned code elements.
`geo.allowed_dmas`, `geo.blocked_dmas`	Integer	Array of Nielsen Designated Market Area (DMA) numbers. For a list of values, see the DMA Codes document.
`geo.allowed_zip_codes`, `geo.blocked_zip_codes`	String	Array of zip codes, which are prefixed with the two letter country and hyphen. e.g. `["US-90045"]`. The two letter country code must be upper case and follow the ISO 3166-1 alpha-2 standard, as shown in the Officially assigned code elements. For Canadian postal codes, the letters must be in uppercase, and the space between the characters must be removed. For example, "m6c 1c7" should be formatted as "CA-M6C1C7".
`geo_global_rule`	String	Default: `""` Values: `""` - No global geographic rule (i.e.,follows the normal flow for geo properties) `"allow_all"` - Allows playback from anywhere in the world, except blacklisted locations, which are specified using the `blocked_` properties `"block_all"` - Blocks playback from anywhere in the world, except whitelisted locations, which are specified using the `allow_` properties
`is_default`	Boolean	Default: `false` Setting this to `true` makes the current Playback Right the default. For details, see the notes in the Introduction section.
`name`	String	Optional playback right name
`start_time`, `end_time`	Integer	Epoch time

Playback Rights proxy properties

Field	Type	Description
`blocked_proxies`	Object	Properties related to proxy rights
`blocked_proxies.anonymous`	Boolean	IP address of the client is not available. Includes services that change location to beat DRM, TOR points, temporary proxies, and other masking services.
`blocked_proxies.corporate`	Boolean	Generally considered harmless, but location can be a concern. Identify if multiple users are proxied through a central location or locations, and can share a single network-apparent IP address.
`blocked_proxies.hosting`	Boolean	IP Address belongs to a hosting facility and is likely to be a proxy as end users are not typically located in a hosting facility.
`blocked_proxies.public`	Boolean	Multiple users proxied from a location allowing public internet access.
`blocked_proxies.transparent`	Boolean	IP address of the client is available via HTTP headers, though the value is not necessarily reliable (e.g., it can be spoofed).

Associate restrictions with a video

Use the CMS API to associate a Playback Rights id with a video. You'll use the Playback Rights id that you created in the previous step.

Note that if the restrictions are not at user-level the JWT is not required, and it can be disabled with allow_insecure playback right settings.

CMS API

Each playback rights restriction object can be used with one or more videos.

Base URL

The base URL for the API is:

https://cms.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://cms.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 Playback Rights API must be made from client credentials with the following permissions:

video-cloud/video/read
video-cloud/video/update

Manage restrictions

The CMS API supports the many request types. To update a video, use the following:

Update a video:

Associate a playback_rights_id with a video. This id should exist in the Playback Rights API, which you created in the previous step.

PATCH
        /v1/accounts/{{account_id}}/videos/{{video_id}}
        Content-Type: application/json
        Body: {video object}

Curl example

Add a playback_rights_id to a video.

curl -X PATCH \
          https://cms.api.brightcove.com/v1/accounts/your account_id/videos/your video_id \
          -H 'Authorization: Bearer your access_token' \
          -H 'Content-Type: application/json' \
          -d '{
          "playback_rights_id": "your playback_rights_id"
          }'

Get a specific video:

GET /v1/accounts/{{account_id}}/videos/{video_ids}

For complete details about using the API, see the CMS API Reference.

Configure your player

By default, the Brightcove Player talks to the Brightcove Playback API (PAPI). A new system to manage playback restrictions sits in front of the Playback API. To configure your player, see the following:

Web player

To configure the Brightcove web player, see the Playback Restrictions with Brightcove Player document.

Native Android or iOS player

To configure the native player for Android or iOS, see the Playback Restrictions with the Native SDKs document.

Your own player

If your content is in the Video Cloud library, but you are using your own player, you can make calls to the Playback API as shown in the Overview: Playback API document. Replace the base URL with the following:

https://edge-auth.api.brightcove.com

Instead of using a Policy Key, you will use the JSON Web Token (JWT) for authentication:

Authorization: Bearer {JWT}

Here is a Curl example:

curl -X GET \
        -H 'Authorization: Bearer {JWT}' \
        https://edge-auth.api.brightcove.com/playback/v1/accounts/{your_account_id}/videos/{your_video_id}

For more information on how to create a JSON Web Token (JWT), see Creating a JSON Web Token (JWT).