Getting started

Base URL

All endpoints begin with

https://clarity-data-api.clarity.io

Depending on the API version you are using, you'll either need to specify either /v1 or /v2 suffixes after the base URL.

Authentication

To authenticate every request, a string known as the API Key must be supplied with each request. The API key identifies who is accessing the API.

For each HTTPS request, the API Key should be sent in the x-api-key request header, as in the following example (The actual API key issued is longer but guaranteed to be header-safe with no encoding or escaping necessary).

GET {baseUrl}/{route} HTTPS/1.1 x-api-key: abcd1234

A 403 Forbidden response may be sent if the developer is successfully authenticated but does not have permission to perform the requested action. For example, attempting to GET information about devices the developer has no access to.

Where to find the API key

A unique API Key is provided to each registered Clarity Dashboard user and can be found in the Profile section of Dashboard. Click the icon in the upper right of Dashboard to slide out the information about the current user. The API key is in the Your Account section.

Applications

We also support API keys that are issued to an Application. An application is another kind of user — not a person — that can access the API but cannot log into Dashboard. We recommend you use an application if you are setting up automation, because you can then manage that application-user separately from the person setting it up. It is bad practice to use a person's API key for automation that you will rely on. An application can be created by your org admin or by Clarity personnel. Whoever configures the application should give you the API key.

Knowledge base: How to set up an Application