Authentication

In order to access the API, you need to set up an integration with and create a set of credentials. See the Quick-start guide for how to get started.

There are two different methods of authentication:

• Basic Auth (username / password): Allows a fast and easy way to authenticate to Clarify. This method can be used to access either the Clarify API or the Clarify MQTT broker.
• OAuth 2.0 (credentials file): Uses information in a credentials file to retrieve a short-lived access tokens. This can reduce the risk/damage of leaking credentials in logs or copied cURL command-lines. This method is used to access the Clarify API, and is used as the preferred way of authentication for all of our SDKs.

Basic Auth

Set the Authorization HTTP header to "Basic <TOKEN>" where token is the Base64 encode value of <username>:<password>. However, virtually all HTTP Clients will take care of the encoding for you, including cURL:

Call Clarify using basic Auth credentials

# BASIC_AUTH_USERNAME=<Username from Basic Auth credentials>
# BASIC_AUTH_PASSWORD=<Password from Basic Auth credentials>
curl -u "${BASIC_AUTH_USERNAME}:${BASIC_AUTH_PASSWORD}" \
  --request POST \
  --url https://api.clarify.io/v1/rpc \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: 1.1beta1' \
  --data ...

OAuth 2.0

OAuth 2.0

If you are unfamiliar with the concepts of OAuth 2., 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.

Integrations in Clarify authenticate to Clarify by following what's called the OAuth 2.0 client-credentials flow. To obtain an OAuth 2.0 access token, you must post the clientId and a clientSecret from the Clarify credentials file.

clarify-credentials.json

{
  "apiUrl": "https://api.clarify.io/v1/",
  "integration": "<YOUR_INTEGRATION_ID>",
  "credentials": {
    "type": "client-credentials",
    "clientId": "<YOUR_CLIENT_ID>",
    "clientSecret": "<YOUR_CLIENT_SECRET>"
  }
}

Obtaining a 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.

Once you have the clientId and clientSecret, you can obtain an access token that is valid for about 2 hours:

cURL

# CLIENT_ID=<clientId from credentials file >
# CLIENT_SECRET=<password from credentials file>
curl --request POST \
  --url 'https://api.clarify.io/v1/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id="${CLIENT_ID}" \
  --data client_secret="${CLIENT_SECRET}" \
  --data audience=https://api.clarify.io/v1/

The response from this request looks something like this:

response

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

See Access token response for details.

Using the access token

To access the Clarify API, you must set the Authorization HTTP Header to Bearer <access_token>:

cURL

# ACCESS_TOKEN=<access_token from response>
curl \
  --header "Authorization: ${ACCESS_TOKEN}"
  --request POST \
  --url https://api.clarify.io/v1/rpc \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: 1.1beta1' \
  --data ...

Schema references

Access token response

type: object

Properties

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 describes a particular portion of the API.
expires_in	integer	The time in second until the token expires.
token_type	string	The type of authentication to use when passing the token. For the Clarify API, the value is always Bearer.