API Authentication

Product(s)
Video Cloud
Role(s)
API Developer
Topic(s)
Administration
Authentication
API(s)
Analytics API
Audience API
CMS API
Dynamic Ingest API
Ingest Profiles API
Player Management API
Policy API

In this topic, you will learn how to get client credentials and use them to get temporary access tokens for API calls. This applies to the Ingest Profiles, Dynamic Ingest, and CMS APIs. You can get client credentials that can be used to authorize requests for just one of the APIs, or any combination of the three.

Introduction

Authentication via OAuth2 involves 2 operations:

  1. Get client credentials - a one-time operation per API
  2. Get an access token - before each API request

We will walk through these two operations for the Ingest Profiles API in the following sections.

Client credentials

Client credentials consist of a client_id and a client_secret. These are used a username/password pair when you getting access tokens. Once you create your client credentials, they are valid indefinitely. You can create credentials for one or more accounts, and for any list of API operations you like. In this guide, we'll see how to create credentials for all Ingest Profiles API operations for a single account.

For many API operations, you can get client credentials through the API Authentication UI in Studio, and that is the recommended way to do it. The operations for the Ingest Profiles API are not currently included in the UI, however, so for now you will need to make requests to the OAuth API directly. We will walk through this in the following section.

Get client credentials

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 profile in Studio:
    Account ID
    Account ID
  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:
    BC_TOKEN
    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.cookies, 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 BC_TOKEN from Console
    Get BC_TOKEN from Console

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 this guide. 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

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, we expect the API to 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