Using Authentication APIs

Introduction

Brightcove Playback Restrictions offers an extra level of security when using Dynamic Delivery with DRM-protected or HTTP Live Streaming Encryption (HLSe) content.

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

Here are the APIs available for managing key/license protection:

Register public key
Blacklist tokens
Audit an account

Register public key

You own the private key, and you will use it to generate signed tokens. You will share the public key with Brightcove to verify your tokens. The key API allows you to register your public key with Brightcove.

Key API

The Key API is used to manage your public keys with Brightcove.

Base URL

The base URL for the API is:

https://playback-auth.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-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 Key API must be made from client credentials with the following permissions:

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

Manage keys

The Key API supports the following requests:

Register a new key:

Put the value of your public key in the API request body. You can find the key in the public_key.txt file.

API Request

POST /v1/accounts/{accountID}/keys
    Content-Type: application/json
    Body: {"value": "MFkwEwYHKoZIzj0CAQYIKoZIzj...MyeQviqploA=="}

Using Curl

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {access_token}" \
    -d '{"value": "{your_public_key_value}"}' \
  https://playback-auth.api.brightcove.com/v1/accounts/{accountID}/keys

API Response

{
    "id": "{your_public_key_id}",
    "type": "public",
    "algorithm": "rsa",
    "value": "{your_public_key_value}",
    "createdAt": "2020-01-03T20:30:36.488Z"
  }

List keys:

Get a list of public keys in your account.

GET /v1/accounts/{accountID}/keys

Get one key:

Get the details for a public key in your account.

GET /v1/accounts/{accountID}/keys/{key_Id}

Delete one key:

Delete a public key in your account.

DELETE /v1/accounts/{accountID}/keys/{key_Id}

Blacklist tokens

A token that has been blacklisted will not be considered valid for license requests, even if it would otherwise have been approved. Customers may blacklist up to 100 tokens. If 100 tokens are already blacklisted, a customer must delete one or more tokens to make room for any additional entries.

Blacklist API

The Blacklist API is used to manage your tokens which are blacklisted and considered not valid for license requests.

Base URL

The base URL for the Blacklist API is:

https://playback-auth.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-auth.api.brightcove.com/v1/accounts/{accountID}/blacklist

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

video-cloud/playback-auth/blacklist

Manage blacklisted tokens

Updates to the blacklist may take up to a minute to propagate through the system. The Blacklist API supports the following requests:

Add a token to the blacklist:

PUT  (no  req  body)/v1/accounts/{accountID}/blacklist/tokens/{token}

The entire encoded JWT string is included in the path.

Show current blacklist:

GET  /v1/accounts/{accountId}/blacklist

Check if a token is on the blacklist:

GET  /v1/accounts/{accountID}/blacklist/tokens/{token}

The entire encoded JWT string is included in the path.

Responses:

204 - the token is blacklisted
404 - the token is not blacklisted

Remove a token from the blacklist:

DELETE  /v1/accounts/{accountID}/blacklist/tokens/{token}

The entire encoded JWT string is included in the path.

Audit an account

The Audit API allows you to generate a daily access report for your account's Playback Authorization Service usage. This report includes details along with the authorization response for each session.

Audit API

Here are the details for the Audit API:

Base URL

The base URL for the Audit API is:

https://playback-auth.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-auth.api.brightcove.com/v1/audit/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 Audit API must be made from client credentials with the following permissions:

video-cloud/playback-auth/audit

Generate reports

Use the Audit API to generate a daily access report with session details by following these steps:

Request a daily usage report

Parameters

Field	Type	Description
`accountID`	String	Your Video Cloud account Id
`date`	String	Validations: Format YYYY-MM-DD Date cannot be today (UTC time) Date cannot be greater than 30 days in the past Brightcove does not hold on to the authorization service usage reports after 30 days to follow GDPR compliance

Request

Method	POST
URL	https://playback-auth.api.brightcove.com/v1/audit/accounts/{accountID}/query/{date}
Headers	Authorization: Bearer your access token
Headers	Content-Type: application/json

Response

Sample response (200 OK):

{
	"executionID":  "abcdef-asfdag-dvsbcd"
}

Details:

Field	Type	Description
`executionID`	String	A unique ID associated with a usage report for a specified `accountID` and `date`. This id is passed to the other endpoints below.

Check the status of your report

Request

Method	GET
URL	https://playback-auth.api.brightcove.com/v1/audit/accounts/{accountID}/execution/{executionID}/status
Headers	Authorization: Bearer your access token
Headers	Content-Type: application/json

Response

Sample response (200 OK):

{
	"status":  "completed"
}

Details:

Field	Type	Description
`status`	String	Values: "completed", "processing", "failed"

Fetch your report

Request

Method	GET
URL	https://playback-auth.api.brightcove.com/v1/audit/accounts/{accountID}/execution/{executionID}/report
Headers	Authorization: Bearer your access token
Headers	Content-Type: application/json

Response

Sample response (200 OK):

{
    "signedURL":  "https://signed-url",
    "expirationTime":  1569219842
}

Details:

Field	Type	Description
`SignedURL`	String	The results are returned as an S3 URL that you can download
`expirationTime`	Epoch Timestamp	Signed S3 URLs are valid for 15 minutes

Limitations

The following limitations apply with the initial release of this feature:

There is a limit of 100 blacklisted tokens. After that, an error will be thrown.