On This Page

Getting Access Tokens

In this topic, you will learn how to get access tokens and show you strategies for implementing this logic in your apps.

Getting a token

If you just want to generate an access token for testing an API request, you can use this sample app.

Tokens are obtained from the Brightcove OAuth API. Before you can get access tokens, you first need to obtain client credentials (a client id and a client secret) that are specific to the API and operations that you want access to. To get your client credentials, see Managing API Credentials.

Once you have your credentials, you obtain an access token by making 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

Note that since the Content-Type must be application/x-www-form-urlencoded, the key/value pair will be sent to the API as a URL param even if you put it in the request body.

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

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 expires_in value is the number of seconds that the access token is valid for.

Implementation Strategies

If your app will only be making sporadic calls to the Brightcove APIs, you might as well ignore the expires_in parameter and just fetch a new access token for every call. In that case, the processing sequence will look like this:

Get New Token

On the other hand, if you know that your app will frequently make many API calls in quick succession (for, say, generating long reports), then it will be more efficient to fetch access tokens only when you need them. There are two basic ways of doing this:

Go ahead and try the API call and if you get an UNAUTHORIZED error in response, go fetch a new token and make the API call again. In this case, the processing sequence will look like this:
Get Token with Check for Call Fail

Another approach would be to add the expires_in value to the current time in Epoch seconds each time you fetch a token, and then on later API calls, check the expires time against the current time to see if you need to fetch a new token. In this case, your processing sequence will look like this:
Get Token with Check for Expiration

Postman and Insomnia

Several useful testing tools for REST APIs can be set up to work with the Brightcove OAuth system to get access tokens. We have guides that include steps for doing this for two of most popular cross-platform tools:

Code Samples

Here are some code samples to help you get started.

Shell script example

The first example is a shell script that implements the first implementation logic above: it takes inputs from the user, always gets a new token, and then makes the API call. The script will work on any of the Brightcove APIs, and you may find it useful for testing API calls as you build your app.

Note: this script uses cURL, and also the jq command line app. See Set up cURL and jq for setup instructions. The Python json.tool is also used to pretty-print the response, but that should already be installed on your system.

To run the script, save the code as api-tester.sh on your system, open a command line in the same folder, and enter bash api-tester.sh - you will be prompted for the following inputs:

Ruby example

The next example is a Ruby script that also employs the first implementation logic: always get a token and then make the API call. This example makes a call to the Analytics API, but can be adapted to work with any of the APIs.

Python example

This sample is a Python script that implements the 3rd implementation logic above. It attempts to make an Analytics API call, but if the call fails on an UNAUTHORIZED error, it fetches a new access token and retries the call.

This script also reads the client credentials from an external file - the credentials data file is shown below the Python code.