Overview: Policy API

Introduction

The policy key is used to retrieve video and playlist content from your Video Cloud library using the Playback API.

Also see the API Reference.

Do you need one?

There are only special cases where you need to generate your own policy keys:

• Policy keys are generated for Brightcove Players automatically when you create them. You only need to generate policy keys directly using this API if you wish to get a key with geo-filtering for a player, or to access the Playback API without creating a player - typically this would be for apps created using the device SDKs. See Policy Keys for instructions on how to obtain the policy key for any Brightcove Player.
• Performing video search requests:
  • You must use a search-enabled Policy Key.
  • Policy keys generated for new Brightcove Players are not search enabled by default. You must set this manually using the Policy API.
  • In general, search-enabled Policy Keys should only be stored on a server and not in a browser player or mobile app, since they can be used to list all playable videos. For some accounts this may not be applicable if you don't mind that all of your playable videos can be discovered.
  • Search requests will only return playable videos. For API request/response details, see the Get Videos section of the Playback API Reference.

FAQ

Here are some questions about the Policy API that we commonly get.

Base URL

The base URL for the Policy API is:

https://policy.api.brightcove.com/v1

Account path

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

https://policy.api.brightcove.com/v1/accounts/{{account_id}}

Authentication

Requests are authenticated by an access token passed in an Authorization header:

Authorization: Bearer {access_token}

To get access tokens, follow these steps:

1. Obtain your client credentials ( client_id and client_secret ) through Video Cloud Studio (recommended).

   For access tokens that can be used with policy key create requests, your client credentials are required to have the following permissions in Studio: Players Read and Read/Write

   

   You can also obtain client credentials directly via the Brightcove OAuth API.

2. Once you have client credentials, you can obtain temporary access tokens from the OAuth API.

Required headers

In addition to the Authorization header discussed in the previous section, requests must also have a Content-Type header:

Content-Type: application/json

Create a policy key

To create a new policy key, make a POST request to:

https://policy.api.brightcove.com/v1/accounts/{{account_id}}/policy_keys

Request body

In the request body, include the JSON for the policy:

{
      "key-data": {
        "account-id": "{account_id}"
      }
    }

This is the most basic policy, which restricts access to the account, you must include this in any policy you create. The account id here must match the account id in the request URL, or an error will be returned.

Domain restriction

In addition to limiting access to the account, you can also limit access to specific domains by adding the allowed-domains key:

{
      "key-data": {
        "account-id": "123456789001",
        "allowed-domains": [
          "https://www.abc.com",
          "https://www.abc.com",
          "https://www.xyz.com",
          "https://www.xyz.com"
        ]
      }
    }

Geo restriction

The Policy API can be used to implement geo-filtering for a player instead of or in addition to individual videos.

Sample

Here is an example whitelist policy set that only allows playback from the US and US territories and military bases:

{"account-id": "8523232323",
      "geo": {
        "countries": ["us", "usmil", "pr", "gu", "vi", "as", "mp"],
        "exclude_countries": false
      }
    }

To blacklist those countries instead, set exclude_countries to true.

Require SSAI

When working with Server-Side Ad Insertion (SSAI), you may want a way to enforce proper ad configuration in your API requests. You can do this by configuring your policy key to require that an ad_config_id is appended as a URL parameter to all Playback API requests.

Sample

Here is an example:

{
      "key-data": {
        "account-id": "1752604059001",
        "require-ad-config": true
      }
    }

For details about using the ad_config_id with your Playback API requests, see the Playback API Overview: Video request with SSAI document.

Search videos

When performing a video search request, you must use a Policy Key that is search-enabled. To create a search-enabled Policy Key, the request body of the call must include the following:

{
      "key-data": {
        "account-id": "57838016001",
        "apis": ["search"]
      }
    }

API Response

The response to policy create requests will be JSON that includes the encrypted key-string that you can use to authenticate requests to the Playback API, as well as the policy associated with the key:

{
      "key-data": {
        "account-id": "57838016001"
      },
      "key-string": "BCpkADawqM0NK0Rq8n6sEQyWykemrqeSmIQqqVt3XBrdpl8TYlvqN3hwKphBJRnkPgx6WAbozCW_VgTOBCNf1AQRh8KnmXSXfveQalRc5-pyNlSod5XzP99If2U"
    }

Policy requests

To retrieve the policy object associated with a key-string , make a GET request to:

/accounts/v1/{{account_id}}/policy_keys/{key_string}

The response will be JSON representation of the key-string and policy:

{
      "key-data": {
        "account-id": "57838016001"
      },
      "key-string": "BCpkADawqM0NK0Rq8n6sEQyWykemrqeSmIQqqVt3XBrdpl8TYlvqN3hwKphBJRnkPgx6WAbozCW_VgTOBCNf1AQRh8KnmXSXfveQalRc5-pyNlSod5XzP99If2U"
    }

Revoke a policy

If you need to revoke an existing policy, submit a request to Brightcove Support. Include the key string for the policy you want to revoke in your request.