Authentication

Clarity adheres to OAuth2 standards to ensure the safety and security of client data. Every API request requires authentication through a pre-generated JWT access token. To generate an access token, please refer to the /token endpoint, detailed in the Generate JWT endpoint documentation page.

Example to generate an access token

To generate an access token, initiate a request with the provided credentials, including the username and password.

import requests
from requests.auth import HTTPBasicAuth

username = 'CLARITY_API_USERNAME'
password = 'CLARITY_API_PASSWORD'

url = 'https://api.getclarity.ai/v1/users/token'

# Sending a GET request with basic authentication
response = requests.post(url, auth=HTTPBasicAuth(username, password))

# Check the response
if response.status_code == 200:
    print('Request was successful!')
    print(response.text)
else:
    print(f'Request failed with status code {response.status_code}')
    print(response.text)

Response example:

{  
    "access_token": "<JWT-ACCESS-TOKEN>",  
    "expires_in": 86400,  
    "token_type": "Bearer"  
}

Subsequently, acquire the <JWT-ACCESS-TOKEN> and securely store it within your application's cache.

Security

The access token generated remains valid for a specified duration. It is incumbent upon the developer to securely store the access token within the application's cache, ensuring its availability for utilization across all Clarity API endpoints.

Rate limit

The /token endpoint is subject to rate limitations; thus, it is imperative to avoid making HTTP requests to this endpoint every second, as it may result in errors. Developers are required to optimize their program by implementing robust caching mechanisms, ensuring that the /token request is triggered only upon expiration of the JWT. A straightforward approach to identify token expiration is to monitor for a 401 Unauthorized HTTP error returned by a Clarity API endpoint.

Using the access token

After generating a JWT and securely storing it in your cache, you can initiate API requests. To utilize the access token, include an Authorization header in your request with the format Bearer <ACCESS_TOKEN>. It is essential to note that every request to Clarity API endpoints mandates the presence of the Authorization header. A straightforward example of including the Authorization header is as follows:

curl -X GET  
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"  
  https://api.getclarity.ai/<endpoint>