Overview: Policy API

In this topic, you will learn what the Policy API is for and how to use it. The Policy API is used to create or get policy keys that can be used to access the Playback API.

Do you need one?

FAQ

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

Can policy keys be created for multiple accounts, or only one?
Policy keys allow access to videos and playlist for one account. If you have multiple accounts, you need to create policy keys for each one.
Do policy keys expire?
No, policy keys are good forever. If you need to revoke a policy key, you must contact Brightcove Support - include the account id and the policy key you wish to revoke in the request.
Will policy keys work for all users on the account?
Yes, anyone who has the policy key can use it.

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 a access token passed in an Authorization header:

Authorization: Bearer {access_token}

To get access tokens, you will need to have client credentials for the account that have permissions for video-cloud/player/all operations. You can obtain your client credentials (a client_id and client_secret) through Studio (recommended) or directly via the Brightcove OAuth API.

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

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 (concise format)

In the request body, include the JSON for the policy - this is the concise format (see the full format below):

{
    "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": [
            "http://www.abc.com",
            "https://www.abc.com",
            "http://www.xyz.com",
            "https://www.xyz.com"
        ]
    }
}

Request body (full format)

Geo restriction

The Policy API can be used to implement geo-restriction 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.

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",
    "policies": [
        {
            "effect": "deny",
            "pattern": {
                "!=": [
                    "[request.params.account-id]",
                    "57838016001"
                ]
            }
        }
    ]
}

Note: the policies in responses is just a different expression of the key-data for the policy, for information only - you do not need to use it in any way.

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",
    "policies": [
                    {
                        "effect": "deny",
                        "pattern": {
                            "!=": [
                                "[request.params.account-id]",
                                "57838016001"
                            ]
                        }
                    }
    ]
}

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.