Version: 1.1

Transport protocol (HTTP)

The transport layer's main role is to connect the client with the underlying RPC API. In order to reach the API, we are relying on plain HTTP POST requests, where the RPC request is embedded within the body. However, in order to reach the API, there are also a few other things that need to be in order. First of all, we need to be able to authenticate the integration. We do this by checking the Authorization header, to see that it contains either valid basic auth credentials or a valid OAuth 2.0 access token. Secondly, we need to know that the request body contains JSON; if not, there is no reason to connect it to a JSON RPC API. Thirdly, we need to connect it to an API version that matches what the integration was actually written for. We do this by checking the X-API-Version header.

HTTP Request headers

The following HTTP request headers are expected by the Clarify API.

Name	Content	Required	Description
`Authorization`	`"<type> <base64 encoded content>"`	Yes	OAuth2 Access Token granting access to Clarify.
`Content-Type`	`"application/json"`	Yes	MIME type used to encode the request body. Must always be `"application/json"`.
`X-API-Version`	`"1.1"`	No	Select which API version to use. If omitted, the latest stable version is used.

Read up on Authentication and Version selection for more details.

HTTP Response Status Codes

JSON RPC 2.0 and Status codes

Note that unlike e.g. REST APIs, JSON RPC 2,0 does not use HTTP status codes for errors. This is because JSON RPC is transfer protocol agnostic. Always check the error in the response body when retrieving a 2xx status code.

A non 2xx status code will be returned if the transport of the RPC request to the the target API, or the transport of the response back to the client failed to complete.

Status code	Description
`200 OK`	Successful transport of RPC request (when the JSON RPC `"id"` field was set).
`204 No Content`	Successful transport of RPC notification request (when the JSON RPC `"id"` field was not set).
`5xx Server Errors`	5xx codes indicate that the API either could not be reached or did not respond as expected.
`401 Unauthorized`	Invalid, missing or expired API credentials.
`400 Bad Request`	Transport to API not possible with current headers. E.g. `X-API-Version` not found or invalid `Content-Type` etc.

Version selection

Version selection of the currently viewed API version is done by adding the following HTTP header:

X-API-Version: 1.1

If the version selection header is omitted, then the latest stable release will be selected.

Example

cURL
# 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.1' \
  --data ...

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.1' \
  --data ...

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 who familiar with the general concepts, but wants 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 24 hours:

cURL
# CLIENT_ID=<clientId from credentials file >
# CLIENT_SECRET=<clientSecret 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"
}

Access token response

type: object

Field	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`.

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.1' \
  --data ...

HTTP Request headers​

HTTP Response Status Codes​

Version selection​

Example​

Authentication​

Basic Auth​

OAuth 2.0​

Obtaining a token​

Access token response​

Using the access token​