Quick Start: OAuth API

This tutorial guides you through the steps to get client-credentials and an access token using the OAuth API.

Requirements

  • API calls in this tutorial use cURL, which is built in on MacOS and all linux/unix systems. If you are running Windows, see Set Up cURL
  • You will need Terminal or some other command-line console for your system

Overview

There are 2 parts to using the Brightcove OAuth API to get access to other Brightcove APIs

  • Get client credentials (a client_id and client_secret) that are valid for the account(s) and API operation(s) you need - this is a one-time operation, provided you save your client_id and client_secret in some secure place for future use
  • Get an access_token that provides authorization to make an API call - the access_token is valid for 5 minutes, so in most cases you will get one for each API call you make

There is also a UI in Studio that you can use to obtain and manage client-credentials. It is recommended that you use the UI whenever possible. For new APIs, the credentials may not be available via the UI for some time, in which case you can get credentials directly from the OAuth API, as you will learn how to do in the steps that follow.

Get client credentials

In these steps we will use a cURL command to get client credentials for the Player Management API.

Steps

  1. Make sure you have cURL available as explained in Requirements; you can test by going to a command line and typing curl and pressing return - if cURL is installed, you should see a message like this:
            curl: try 'curl --help' or 'curl --manual' for more information
  2. Now you need two pieces of information that you can obtain from Studio. Login to Studio by going to Studio.
    • account id
    • BC_TOKEN

    Note: The BC_TOKEN value is a cookie set when you open Studio. It has no relation to the API Management tokens you deal with in Studio.

Get your account id and BC_TOKEN

  1. First you will need your account id from the Account Information.
  2. Click the settings icon Account Settings in the Studio header.
  3. Select Account Information from the dropdown.
  4. Copy your account id from the Account Information page and save it - you will need it in a later step.
  5. Now open the browser developer console - in most browsers you can do this by pressing OPTION-CMD-i (Mac) or ALT-CTRL-i (Windows), or you should be able to find a menu item also.
  6. In the console, paste the following JavaScript and press return to display your BC_TOKEN in a modal dialog:
  7. Copy the BC_TOKEN to the clipboard.
  8. Enter your account id and BC_TOKEN here:

    Account id:

    BC_TOKEN:

Make the credentials request

  1. To get your client credentials, copy and paste the following cURL command at your command line and press return:
  2. The response should look like this (formatting added):
            {"redirect_url":null,"maximum_scope":[{"identity":
            {"type":"video-cloud-account","account-id":57838016001},
            "operations":["video-cloud/player/all"]}],"name_html":"Sample-Client",
            "issued_to":"rcrooks@brightcove.com","trusted":null,"expires_at":null,
            "issued_at":"2015-06-18T20:17:12Z","name":"Sample-Client",
            "description_html":null,"revoked":null,"type":"credential",
            "client_secret":"PiQ5s3-tk46DvNBPauknctP3aTIS07zNIa7Kxz3b7hnRMA5JvQdkwa7JpyuX7dnD4RXziA4KEK0n1pEO94Q7,
            "description":null,"client_id":"b63e5ac2-5264-4a5a-971a-a133bc7bd605",
            "issued_user":53255203001}

    This is not a valid client secret - you should never expose a client secret publicly.

  3. Enter the values for the client_id and client_secret below, as you will need these anytime you need to get an access_token.
    Client Credentials

    client_id:

    client_secret:

Get access tokens

The client_id and client_secret you obtained in the previous steps are used as a username:password combination for authentication when you request an access_token. In cURL, which we will use here, you can pass these as the --user parameter. In other languages, you will pass these in a Basic Authorization header with your HTTP request:

        Authorization: Basic {client_id:client_secret}

Note: the entire client_id:client_secret must be Base64-encoded to be accepted by the OAuth API. cURL will Base64-encode the --user credentials automatically, but in other languages you will need to Base64 encode it yourself.

Steps

  1. To get your access_token, copy and paste the following cURL command to your command line and press enter:
  2. The output should look like this:
            {"access_token":"ACkkpftcuhyzqdf4ftxm304za3anhziG0Ni5-S_dplxMNYNrSrBZRgJL3sf_U38ZZVDdgkmWtrb0_GRZj-VzWOAFWgpEYwgwIWLjcGsTI-9QMUMNv2eFj33clsWFHnGLzgtdcILXpR-wPM0LzKKzRahodwofPfuExYCej18Wpt1x7DxOJDySEjCGOWiTuZVKp1QjG0_nqD9T3TpK3Cchv0suVRTGkYrs15qYSKdxh2-e5XbUiKKptNl8ryvMriavPN66fOh17c09Q0525OPqejkU6uERPTw-sTLU_QjJbRV6psxoSVYKRAetsBikH9XRJbZCSt2JP88O","token_type":"Bearer","expires_in":300}
  3. This token can be used to authenticate calls to Player Management API for 5 minutes (then you need to get a new token). The token is passed in the Authorization header with the HTTP request:
            Authorization: Bearer access_token value