Page Contents

    Additional APIs for Playback Authorization Service

    In this topic, you will learn about additional APIs available for content protection when using Brightcove's Playback Authorization Service.

    Introduction

    Brightcove's Playback Authorization Service (PAS) 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: DRM with Playback Authorization Service document.

    There are additional APIs available to you for managing your content using PAS. They allow you to do the following:

    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:

    1. 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
      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.
    2. 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
      Content-Type: application/json

      Response

      Sample response (200 OK):

      {
      	"status":  "completed"
      }
      

      Details:

      Field Type Description
      status String Values: "completed", "processing", "failed"
    3. 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
      Content-Type: application/json

      Response

      Sample response (200 OK):

      {
          "signedURL":  "http://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.

    Page last updated on 24 Sep 2021