Access tokens

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

Below are a few examples of how to exchange your client credentials for an access token. This can be done via normal HTTP calls (like the cURL example), but since we recommend using a library that takes care of token renewal on expiry we have done so in the examples below.

curl --request POST \
2  --url '<<tokenURL>>' \
3  --header 'content-type: application/x-www-form-urlencoded' \
4  --data grant_type=client_credentials \
5  --data client_id=<YOUR_CLIENT_ID> \
6  --data client_secret=<YOUR_CLIENT_SECRET> \
7  --data audience=https://api.clarify.io/v1/
package main

import (
    "context"
    "fmt"
    "net/url"

    "golang.org/x/oauth2/clientcredentials"


func main() {
    config := &clientcredentials.Config{
        ClientID:       "<YOUR_CLIENT_ID>",
        ClientSecret:   "<YOUR_CLIENT_SECRET>",
        TokenURL:       "<<tokenURL>>",
        EndpointParams: url.Values{
        "audience": []string{
            "<<apiURL>>"
      }
    },
    }

    ctx := context.Background()

    token, err := config.Token(ctx)
    if err != nil {
    // TODO: handle error properly
        fmt.Println(err)
        return
    }

    fmt.Println(token.AccessToken)

  // Usually one would use config.Client(ctx) that returns a http client
  // that handles accessToken and renewal automatically. 
  // See our next example for details on how to use that.
  
}
// npm install --save simple-oauth2

const { ClientCredentials } = require("simple-oauth2");
const config = {
  client: {
    id: "<YOUR_CLIENT_ID>",
    secret: "<YOUR_CLIENT_SECRET>",
  },
  auth: {
    tokenHost: "<<tokenURL>>",
  },
};

async function run() {
  let client = new ClientCredentials(config);
  try {
    let accessToken = await client.getToken({
      audience: "<<apiURL>>",
    });
    console.log("access_token", accessToken);
  } catch (error) {
    console.log("Access Token error", error);
  }
}

run();
from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session

session = OAuth2Session(client = BackendApplicationClient(client_id = '<YOUR_CLIENT_ID>'))

try:
    session.fetch_token(body= 'audience=<<apiURL>>', token_url = '<<tokenURL>>', client_secret = '<YOUR_CLIENT_SECRET>')
except:
    raise Exception('failed to get access token: {}'.format(format_exc()))

print(session.access_token)

❗️

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 response from the cURL example above will be like the one below and will include the access token, a defined scope, number of seconds until expiration and the type of authentication to use when passing the token to the Clarify API, for our APIs the value is always Bearer. When using libraries for authentication the end-user response might vary a bit, but the essentials are the same.

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

Did this page help you?