---
title: Authentication - APIs
description: How to authenticate to the Contentsquare public APIs using server-to-server OAuth 2.0 credentials.
source_url:
  html: https://docs.contentsquare.com/en/api/authentication/
  md: https://docs.contentsquare.com/en/api/authentication/index.md
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.

All Contentsquare public APIs authenticate the same way, using server-to-server OAuth 2.0 credentials (also known as 2-legged OAuth, or OAuth 2LO) generated from the Contentsquare console.

> **Warning**
>
> **API keys are no longer supported**. You must use OAuth credentials instead to authenticate on our APIs, and migrate your existing applications using API keys.

## OAuth2 authentication

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_ACCESS_TOKEN`). The OAuth credentials themselves (the `client_id` / `client_secret` pair) expire after 1 year.

The response also includes the base URL (`endpoint`) you should use to query the API with that token. For most APIs this is a fixed URL, but the Enrichment API returns a URL that depends on the cloud the project is installed on — see [Authentication endpoint](https://docs.contentsquare.com/en/api/authentication/#authentication-endpoint) below for details.

> **Warning**
>
> Your OAuth credentials carry many privileges, so make sure to keep them secure! Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth.

### Create credentials

You can generate a pair `client_id` / `client_secret` from the Contentsquare [console ↗](https://console.contentsquare.com), as a Contentsquare administrator.

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

You'll find the same **API Credentials** tab at both the account level and the project level.

1. Go to the account or project level, open the **API Credentials** tab, and start creating new credentials.
2. Name your credentials and, optionally, restrict them to a list of allowed IP addresses (IPv4 or IPv6). By default, any IP can use them.
3. Confirm to create them. A pop-up displays your generated `client_id` and `client_secret`. Store them somewhere secure: Contentsquare doesn't keep a copy, and this is the only time they're shown. Click **I copied my credentials** to close the pop-up.

Your new credentials appear in the **API Credentials** tab and are ready to use with the Contentsquare APIs. You can create up to 10 credentials per account and per project (see [Limits](https://docs.contentsquare.com/en/api/authentication/#limits)).

With account-level credentials, you must pass a `project_id` in your token request, whichever API you target.

> **Note**
>
> Enrichment API credentials aren't created this way. Customers get them, along with the project ID, when they install an integration, and share them with the integration's provider. See [Installing integrations](https://docs.contentsquare.com/en/api/enrichment/installing-integrations/).

### Regenerate credentials

Regenerating credentials invalidates the previous `client_secret` for that connection, so update any application that still uses it.

1. Go to the **API Credentials** tab, open the **...** menu next to the credentials, and select **Regenerate credentials**.
2. Confirm the action.
3. Copy and store the new `client_secret` from the pop-up: you won't be able to view or recover it afterward.

### Edit credentials

Editing credentials lets you change their name, description, or IP allowlist without generating a new `client_secret` — the existing credentials keep working.

1. Go to the **API Credentials** tab, open the **...** menu next to the credentials, and select **Edit credentials**.
2. Update the name, description, or allowed IPs, then save your changes.

### Revoke credentials

Revoking credentials deletes them permanently and immediately breaks any application still using them.

1. Go to the **API Credentials** tab, open the **...** menu next to the credentials, and select **Revoke credentials**.
2. Confirm the action. The credentials are removed from the list and can no longer be used to query Contentsquare's public APIs.

## Authentication endpoint

POST `https://api.contentsquare.com/v1/oauth/token`

### Request parameters

* `client_id`  *string*  **Required**

  The OAuth `client_id` generated from the Contentsquare console.

* `client_secret`  *string*  **Required**

  The OAuth `client_secret` generated from the Contentsquare console.

* `grant_type`  *string*  **Required**

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

* `scope`  *string*  **Required**

  The scope to request, depending on which API you want to query: `enrichment`, `data-export`, `metrics`, `surveys`, or `speed-analysis`.

  You can specify a list of several scopes (for example `"data-export metrics"`) to get a single token that can query several APIs. The only scope that cannot be combined with other scopes is `enrichment`.

* `project_id`  *integer*  

  Required only if you use account-level OAuth credentials, to specify which project of the account you want to target.

* `integration_id`  *integer*  

  Required only if you use the `enrichment` scope. This is the ID of the target integration. This ID is provided by Contentsquare when installing the [integration](https://docs.contentsquare.com/en/api/enrichment/definitions/#integration) on a project.

### Scopes

| API | `scope` | Extra request parameters | Base URL (`endpoint`) |
| - | - | - | - |
| [Data Export](https://docs.contentsquare.com/en/api/export/) | `data-export` | `project_id`\* | `https://api.contentsquare.com` |
| [Metrics](https://docs.contentsquare.com/en/api/metrics/) | `metrics` | `project_id`\* | `https://api.contentsquare.com` |
| [Responses](https://docs.contentsquare.com/en/api/responses/) | `surveys` | `project_id`\* | `https://api.contentsquare.com` |
| [Enrichment](https://docs.contentsquare.com/en/api/enrichment/) | `enrichment` | `integration_id` | `https://enrichment-api.{cloud}.contentsquare.com` |
| [Speed Analysis Lab](https://docs.contentsquare.com/en/api/speed-analysis-lab/) | `speed-analysis` | `project_id`\* | `https://api.contentsquare.com` |

\* Required with account-level credentials only.

Always use the `endpoint` value from the token response as the base URL. For Enrichment, `{cloud}` depends on which cloud the project is installed on.

### Request and response examples

```shell
curl --location 'https://api.contentsquare.com/v1/oauth/token' \
--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
}'
```

```json
{
  "access_token": "eyJhbGciOiJSIsImtpY5MTXXX.CNTcKWAUb2mTp2cZyiDRYYOtGCKXXX",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "data-export",
  "project_id": 42,
  "endpoint": "https://api.contentsquare.com"
}
```

For the Enrichment API, set `scope` to `enrichment` and add the `integration_id`. The returned `endpoint` is then cloud-specific:

```json
{
  "access_token": "eyJhbGciOiJSIsImtpY5MTXXX.CNTcKWAUb2mTp2cZyiDRYYOtGCKXXX",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "enrichment",
  "project_id": 42,
  "endpoint": "https://enrichment-api.ba.contentsquare.com"
}
```

### Errors

If the request fails, the authentication endpoint returns an OAuth error body:

```json
{
  "statusCode": 401,
  "error": "invalid_client",
  "error_description": "client authentication failed",
  "message": "client authentication failed"
}
```

* `401` with `invalid_client`: the `client_id` / `client_secret` pair is wrong, or the credentials can't be used for this request. Check that the credentials haven't been revoked or expired, and that your IP address is in the credentials' allowed IP list, if you set one.
* `400` with `invalid_request`: a parameter is missing or malformed. The `error_description` names it, for example `parameter client_secret is invalid`.
* `403`: the credentials have no access to the requested `project_id` or `scope`.

## Refresh your access token

Once you [get a JWT access token](https://docs.contentsquare.com/en/api/authentication/#authentication-endpoint), it's valid for 1 hour. If you query the Contentsquare APIs with an expired or invalid access token, you receive a `401 Unauthorized` error, in one of the following forms:

```json
{
  "success": false,
  "errorMessage": "Auth token is expired.",
  "errorCode": "JWT_EXPIRED"
}
```

```json
{
  "success": false,
  "errorMessage": "Auth token is invalid.",
  "errorCode": "JWT_INVALID"
}
```

If you send no `Authorization` header at all, you receive a `401 Unauthorized` error too:

```json
{
  "success": false,
  "errorMessage": "Authentication is required",
  "errorCode": "AUTHENTICATION_REQUIRED"
}
```

**Enrichment API**

```json
{"message":"Unauthorized"}
```

In that case, use your OAuth credentials to request a new access token. If your OAuth credentials have expired, see [Regenerate credentials](https://docs.contentsquare.com/en/api/authentication/#regenerate-credentials) above.

## OAuth credentials information endpoint

POST `https://api.contentsquare.com/v1/oauth/me`

### Request parameters

* `client_id`  *string*  **Required**

  The OAuth `client_id` generated from the Contentsquare console.

* `client_secret`  *string*  **Required**

  The OAuth `client_secret` generated from the Contentsquare console.

### Request example

```shell
curl --location 'https://api.contentsquare.com/v1/oauth/me' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "c3133d76-a768-4f5a-XXX",
    "client_secret": "0ISL0DEC;UyYKB;riWRS0EXXX"
}'
```

### Response example

```json
{
  "scopes": "metrics data-export speed-analysis surveys enrichment",
  "permissions": {
    "projects": [
      {
        "id": 42,
        "name": "UX ANALYTICS"
      }
    ]
  }
}
```

## Example of authentication flow

* Data Export

  End-to-end authentication flow that first retrieves an access token and then uses it to retrieve the list of export jobs on a project:

  ```javascript
  const clientId = "<your_client_id>";
  const clientSecret = "<your_client_secret>";
  const authEndpoint = "https://api.contentsquare.com/v1/oauth/token";
  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;
  ```

* Metrics

  End-to-end authentication flow that first retrieves an access token and then uses it to retrieve the list of segments on a project:

  ```javascript
  const clientId = "<your_client_id>";
  const clientSecret = "<your_client_secret>";
  const authEndpoint = "https://api.contentsquare.com/v1/oauth/token";
  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: "metrics",
    }),
  };
  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 Metrics API endpoints
  const accessToken = authJsonData.access_token;
  const baseURL = authJsonData.endpoint;
  // Using the access token and base URL to query the Metrics API endpoints and get the segments in this example
  const metricsApiEndpointResponse = await fetch(`${baseURL}/v1/segments`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const metricsApiEndpointauthJsonData = await metricsApiEndpointResponse.json();
  const segments = metricsApiEndpointauthJsonData.payload;
  ```

* Responses

  End-to-end authentication flow that first retrieves an access token and then uses it to list the surveys of a project:

  ```javascript
  const clientId = "<your_client_id>";
  const clientSecret = "<your_client_secret>";
  const authEndpoint = "https://api.contentsquare.com/v1/oauth/token";
  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: "surveys",
    }),
  };
  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 Responses API endpoints
  const accessToken = authJsonData.access_token;
  const baseURL = authJsonData.endpoint;
  // Using the access token and base URL to list the surveys of a project in this example
  const responsesApiEndpointResponse = await fetch(`${baseURL}/v1/public/projects/42/surveys`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const responsesApiEndpointauthJsonData = await responsesApiEndpointResponse.json();
  const { results, next_cursor } = responsesApiEndpointauthJsonData;
  ```

* Enrichment

  End-to-end authentication flow that first retrieves an access token and then uses it to send a batch of enrichment data to a project:

  ```javascript
  const clientId = "<your_client_id>";
  const clientSecret = "<your_client_secret>";
  const authEndpoint = "https://api.contentsquare.com/v1/oauth/token";
  const authRequestOptions = {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: clientId,
      client_secret: clientSecret,
      grant_type: "client_credentials",
      scope: "enrichment",
      project_id: 42,
      integration_id: 123,
    }),
  };
  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 Enrichment API endpoints
  const accessToken = authJsonData.access_token;
  const baseURL = authJsonData.endpoint;
  // Using the access token and base URL to send a batch of enrichment data
  await fetch(`${baseURL}/v1/enrichments`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      integrationVersion: 1,
      projectId: 42,
      enrichments: [
        {
          userId: "<user_id>",
          sessionNumber: 5,
          enrichment: { has_called: true },
        },
      ],
    }),
  });
  ```

  See [Sending enrichment data batches](https://docs.contentsquare.com/en/api/enrichment/sending-enrichment-data-batches-cs/) for the full payload.

* Speed Analysis Lab

  End-to-end authentication flow that first retrieves an access token and then uses it to retrieve the list of monitorings on a project:

  ```javascript
  const clientId = "<your_client_id>";
  const clientSecret = "<your_client_secret>";
  const authEndpoint = "https://api.contentsquare.com/v1/oauth/token";
  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: "speed-analysis",
    }),
  };
  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 Speed Analysis Lab API endpoints
  const accessToken = authJsonData.access_token;
  const baseURL = authJsonData.endpoint;
  // Using the access token and base URL to query the Speed Analysis Lab API endpoints and get the monitoring list in this example
  const speedAnalysisLabResponse = await fetch(`${baseURL}/v1/speed-analysis/monitoring/list`, {
    method: "POST",
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const data = await speedAnalysisLabResponse.json();
  const monitorings = data.payload.monitorings;
  ```

## Limits

All Contentsquare APIs share the following limits:

* 10 concurrent requests maximum per project. Beyond that, requests fail with a `429` error.
* 10 OAuth credentials (`client_id` / `client_secret`) per project and per account maximum.

> **Note**
>
> **Limitations are tracked at the project level**, not at the OAuth credentials level. So if you have created several OAuth credentials requesting resources for a target project, the total number of concurrent requests must not exceed 10 for a specific project, all credentials taken into account.

Some APIs add their own limits: see [Data Export API limits](https://docs.contentsquare.com/en/api/export/limits/) and [Metrics API limits](https://docs.contentsquare.com/en/api/metrics/limits/).


```json
{"@context":"https://schema.org","@type":"TechArticle","headline":"Authentication","description":"How to authenticate to the Contentsquare public APIs using server-to-server OAuth 2.0 credentials.","url":"https://docs.contentsquare.com/en/api/authentication/","inLanguage":"en","dateModified":"2026-11-20T10:14:49+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}}
```