The Contentsquare APIs use the server-to-server OAuth 2.0 standard for authentication, also know as 2-legged OAuth or OAuth 2LO.

The flow basically consists in calling an authentication endpoint with a pair client_id / client_secret to retrieve an access token that remains valid for 1 hour. This JWT token should then be used as a Bearer token in the headers of your HTTPS requests (in the form Authorization: Bearer YOUR_API_KEY).

Note that the API call to the authentication endpoint will also dynamically return the right base URL that you must use. This base URL depends on which cloud the target project is installed on.

You can refer below to a detailed example of the overall flow to retrieve a token and a base URL, and use those to make query the Data Export API.

You can generate a pair client_id / client_secret from the Contentsquare console, as a Contentsquare administrator. You can find how to generate these credentials in our Help Center documentation.

You can create OAuth credentials either:

  • At the Project level, to request access resources from a specific project only
  • At the Account level: to request access for any project of the account

Once you get a JWT access token (see the authentication endpoint below), it’s valid for 1 hour. If you try to query the Contentsquare APIs with an access token that has expired, you will receive a 401 Unauthorized error with the error code JWT_EXPIRED, in the form:

"success": false,
"errorMessage": "Auth token is expired.",
"errorCode": "JWT_EXPIRED"

In that case, you should first use your OAuth credentials (your pair client_id / client_secret) to query a new access token. The OAuth credentials don’t expire.


These parameters have to be provided in the body of the request.


Required. The OAuth client_id generated from the Contentsquare console


Required. The OAuth client_secret generated from the Contentsquare console


Required. Always set it to "client_credentials", as required by the OAuth 2.0 standard


Required. You should use "data-export".
If needed, you can specify a list of several scopes to get a token that can query several APIs (e.g. "data-export metrics" if you want your token to cover both the Data Export API and Metrics API scopes). The only scope that cannot be combined with other scopes is enrichment.


Optional. Only required if you use account-level OAuth credentials, to specify which project of the account you want to target

Terminal window
curl --location '' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "c3133d76-a768-4f5a-XXX",
"client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX",
"grant_type": "client_credentials",
"scope": "data-export",
"project_id": 42
"access_token": "eyJhbGciOiJSIsImtpY5MTXXX.CNTcKWAUb2mTp2cZyiDRYYOtGCKXXX", // to be used as bearer token to query the APIs
"token_type": "bearer",
"expires_in": 3600,
"scope": "data-export",
"project_id": 42,
"endpoint": "" // this is the base URL you should use to query the Data Export API endpoints - the providded URL depends on the cloud the project is installed on

Example of authentication flow

Section titled Example of authentication flow

Below is a sample of Javascript code to show a complete API call flow that first retrieves an access token and then use it to retrieve the list of export jobs on a project:

const clientId = "<your_client_id>";
const clientSecret = "<your_client_secret>";
const authEndpoint = "";
const authRequestOptions = {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: clientId,
client_secret: clientSecret,
grant_type: "client_credentials",
project_id: 42,
scope: "data-export",
const authResponse = await fetch(authEndpoint, authRequestOptions);
const authJsonData = await authResponse.json();
// Below are the access token and base URL that must be used to query the Data Export API endpoints
const accessToken = authJsonData.access_token;
const baseURL = authJsonData.endpoint;
// Using the access token and base URL to query the Data Export API endpoints and get the export jobs in this example
const dataExportApiEndpointResponse = await fetch(`${baseURL}/v1/exports`, {
headers: { Authorization: `Bearer ${accessToken}` },
const dataExportApiEndpointauthJsonData =
await dataExportApiEndpointResponse.json();
const exports = dataExportApiEndpointauthJsonData.payload;

OAuth credentials information endpoint

Section titled OAuth credentials information endpoint



Terminal window
curl --location '' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "c3133d76-a768-4f5a-XXX",
"client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX",
"scopes": "metrics data-export session-replay symbolicator",
"permissions": {
"projects": [
"id": 42,
"name": "UX ANALYTICS"