Authentication for API Requests

Introduction

Most of the Brightcove REST APIs use OAuth2 as the basis for authentication, and we'll look at the OAuth implementation in more detail in the sections that follow.

First, however, note that two APIs use different approaches to authentication:

        Accept: application/json;pk={policy_key}

        X-API-KEY : {YOUR_APIKey}

OAuth2 authentication

The other REST APIs for Video Cloud use OAuth2 for authentication, For those familiar with OAuth2, we use a client credential flow. There are two operations involved:

1. Get client credentials: this is a one-time operation that is most easily carried out using the API Authentication page of the Admin tools in Studio. See Managing API Authentication Credentials for details and step-by-step instructions.
2. Get an access token: each API request must contain an access token sent in an Authorization header:

           Authorization: Bearer {access_token}

   Access tokens live for five minutes, so unless you running a process that will be generating repeated API requests, you will probably just want to get a new one for each request.

   Access tokens are obtained by sending the client credentials in a request to Brightcove's OAuth API. See Getting Access Tokens for full details. There is also a sample app you can use to get a one-off token for testing API calls. There are also instructions for configuring the popular REST clients Postman and Insomnia.

Client credentials via the OAuth API

If you want or need to create client credentials using the OAuth API, below are steps that will guide you through getting your client credentials. You will first need to get your BC_TOKEN, which is used to authenticate you for the client credentials request.

Get your BC_TOKEN and account number

You will need to login to Studio to get your BC_TOKEN.

1. Login to Studio as you normally do.
2. You need your account number (referred to as the Publisher ID in Studio), which you can get by going to your account information in Studio:

   

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

4. You should see a prompt appear that contains your BC_TOKEN:

   

5. If you have your BC_TOKEN, go on to the Get client credentials section; if for some reason you did not get your BC_TOKEN using the previous steps, just go to the Console, type document.cookie, and press return.
6. All cookies for the page will be returned in a semi-colon-separated list. Find the BC_TOKEN cookie in the list, and copy the value:

   

Get client_credentials

Now we are ready to make the call to the OAuth service to retrieve client credentials. We have to specify a client application name that we are requesting credentials for - the name is arbitrary, intended to help you keep track of what the credentials are for - and here we will just use "ingest-profiles-api-client". We also have to specify the scope of the operations we want access to in an array, and here we will use. The operations available are shown in API Operations for Client Credentials Requests. In the steps below, you will specify the operations required for the Ingest Profiles API.

1. Edit the following curl command, then paste it into the command line and press Return. You must provide your specific values for the following three values:
   • your BC_TOKEN
   • your credential name
   • your account id

         curl \
           --include \
           --header "Authorization: BC_TOKEN your_BC_TOKEN" \
           --data 'name=ingest-profiles-api-client&maximum_scope=[{
               "identity": {
                 "type": "video-cloud-account",
                 "account-id": your_account_id
               },
               "operations": [
                     "video-cloud/ingest-profiles/profile/read",
                     "video-cloud/ingest-profiles/profile/write",
                     "video-cloud/ingest-profiles/account/read",
                     "video-cloud/ingest-profiles/account/write"
                 ]
             }]' \
         https://oauth.brightcove.com/v4/client_credentials

2. The response should look like this (formatting added):

         {
           "redirect_url": null,
           "maximum_scope": [
             {
               "identity": {
                 "type": "video-cloud-account",
                 "account-id": your_video_cloud_account_id
               },
               "operations": [
                 "video-cloud/ingest-profiles/profile/write",
                 "video-cloud/ingest-profiles/account/write",
                 "video-cloud/ingest-profiles/profile/read",
                 "video-cloud/ingest-profiles/account/read"
               ]
             }
           ],
           "name_html": "ingest-profiles-api-client",
           "issued_to": "your_email@host.com",
           "trusted": null,
           "expires_at": null,
           "issued_at": "2015-06-01T15:09:00Z",
           "name": "ingest-profiles-api-client",
           "description_html": null,
           "revoked": null,
           "type": "credential",
           "client_secret": "Ifckr6cWtxOh_NZnEVhKCgcqZaqoMcPuoJ-VGuivIE_psPoPUt2hGqUK15uPON3x3m748ElazZoOKPxbI3-4nQ",
           "description": null,
           "client_id": "da270d86-f3cd-4ee6-85b0-047df97a0db2",
           "issued_user": your_video_cloud_account_id
         }

3. Copy and save the client_id and client_secret, as you will need these anytime you need to get an access_token.

Access tokens via the OAuth API

Access tokens, unlike client credentials, are short-lived - currently they expire in 5 minutes. You will need to get a new one for each API request. You could, of course, build logic into an app to check the most recent access token to see if it has timed out, but requests to the Ingest Profiles API are likely to be few and far between, so there's no good reason to do that.

In fact, the API may be one that you will use infrequently enough that it may not be worth building an app around it at all. An alternative would be to use this shell script that Brightcove Learning Services built. It allows you to enter your client id and secret, the API request and method, and any request data. It then gets an access_token, makes the API request, and outputs the response. (Note that the shell script uses cURL, which is installed natively on Mac MacOS and other Unix/Linux systems, or can be installed on Windows.

To retrieve access tokens you make a POST request to:

      https://oauth.brightcove.com/v4/access_token

You must pass the following headers with this call:

• Content-Type: application/x-www-form-urlencoded
• Authorization: Basic {client_id}:{client_secret}

The entire {client_id}:{client_secret} string must be Base64-encoded (curl will automatically Base64-encode the string if you pass it as --user credentials; in other languages, you'll need to handle the Base64-encoding yourself).

You must also send the following key/value pair as the request body or as URL parameter:

      grant_type=client_credentials

The response will look like this (pretty-printed here for readability):

      {
          "access_token": "ANB7xKhiUZmwltVd3f1odcHHM9VAwg02kwmLwtZwHv3SxGCOWLUf5W4G7X22PRjmR9StvFUqzpVZ1suOfyfOigdi-rnohxyEaSSuZceeLw_9OBW7fXldOG05HEgkeK3N-DBZZZyilodmjA1JWZHbgI3IU7Rmz5IPGyi-sDxHN3KlOr1BDZlLZpXPdFPwEyb6idq-z8AL-blKTSMtNI3_fz3oNBisfrHGUv5tXHoQT4B7FYcvdrap16gTOO7_wNt1zmgLJiUHvyxZgsgBchm_AhohVL-AYgcfCbCR0v7d2hgI4ag35pnZNeujDiBLfnCFcVMlqQGq8UEVZrmU9a8y4pVAGih_EImmghqmSrkxLPYZ800-vIWX-lw",
          "token_type": "Bearer",
          "expires_in": 300
      }

The access_token value is what you must pass in an Authorization header with your API call in this form:

      Authorization: Bearer {access_token}

The expired_in value is the number of seconds that the access token is valid for.

For more information and sample code, see Getting Access Tokens