Contact Support | System Status
Page Contents

    Implementing Playback Rights

    In this topic, you will learn how to manage video playback using Brightcove 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:

    1. Geographic checks
    2. Schedule check
    3. Proxy check
    4. Domain check
    Playback Rights validation
    Playback Rights validation

    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
    Geographic restrictions
    Geographic restrictions

    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:

    1. Schedule check
    2. Proxy check
    3. Domain check
    Additional validation checks
    Additional validation checks

    Workflow

    To manage playback restrictions, follow these steps:

    1. Set up your account
    2. Define restrictions
    3. Associate restrictions with a video
    4. 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 account manager for details.

    Generate OAuth credentials

    Get your BC_TOKEN and account number.

    1. Log into Video Cloud Studio. In the Admin dropdown, select Account Information. Copy your Account ID.
    2. 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.

    3. You should see a prompt appear that contains your BC_TOKEN

    Request client credentials

    Add account permissions for the Playback Rights API.

    1. 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
      Playback Rights Permissions
    2. If you prefer generating your credentials using the OAuth API directly, continue with the following steps.
    3. 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
    4. 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/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-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"
    }

    Here are the field details:

    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.
    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.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).
    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.
    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.
    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

    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.

    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.brigthcove.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}

    Page last updated on 03 May 2021