Get access to the API.

To access the Clarify APIs you will need a set of credentials which can be used to retrieve an access token. These tokens are then included in all API requests to the API and are what ensures that only authorized clients are granted access.

📘

Credentials are downloaded from the Integration tab in the Admin UI.

See the guide on obtaining an access token for details.

{
  "apiUrl": "<<apiURL>>",
  "integration": "<YOUR_INTEGRATION_ID>",
  "credentials": {
    "type": "client-credentials",
    "clientId": "<YOUR_CLIENT_ID>",
    "clientSecret": "<YOUR_CLIENT_SECRET>"
  }
}

Obtaining an Access Token

📘

OAuth 2.0

If you are unfamiliar with the concepts of OAuth, we recommend you read a bit about the concept of it from the oauth.com website.

For those familiar with the general concepts, but wanting to read up a bit about the client_credentials grant type, you can find more about it here.

Access tokens are retrieved using the client_credentials grant in OAuth 2.0 as shown below.

curl --request POST \
  --url '<<tokenURL>>' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET \
  --data audience=https://api.clarify.us/v1/

Access token response

❗️

Expiry

The retrieval of access tokens is a costly operation and is rate limited in the Clarify APIs. Once you have retrieved an Access Token it is important to keep using it until it expires. To read more about the Access Token response and the expiry of a token please go here.

The access token response contain a JSON object with following fields:

Name

Type

Description

access_token

string

Access token describes a token that can be used to access the Clarify API

scope

string

Comma separated list of scopes. A scope describe a particular portion of the API.

expires_in

integer

The time in second until the token expires.

token_type

string("Bearer")

The type of authentication to use when passing in the token. For the Clarify API, the value is always Bearer.

To access the Clarify API, jou must set the Authorization HTTP Header to <token_type> <access_token>.

{
  "access_token":"<YOUR_ACCESS_TOKEN>",
  "scope":"invoke:integration",
  "expires_in":86400,
  "token_type":"Bearer"
}