For the complete documentation index, see llms.txt.

Authentication

Dernière mise à jour Voir en Markdown

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.

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 below for details.

You can generate a pair client_id / client_secret from the Contentsquare console ↗, 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).

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

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.

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.

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.

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

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 on a project.

APIscopeExtra request parametersBase URL (endpoint)
Data Exportdata-exportproject_id*https://api.contentsquare.com
Metricsmetricsproject_id*https://api.contentsquare.com
Responsessurveysproject_id*https://api.contentsquare.com
Enrichmentenrichmentintegration_idhttps://enrichment-api.{cloud}.contentsquare.com
Speed Analysis Labspeed-analysisproject_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.

Terminal window
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
}'
{
"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:

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

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

{
"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.

Once you get a JWT access token, 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:

{
"success": false,
"errorMessage": "Auth token is expired.",
"errorCode": "JWT_EXPIRED"
}
{
"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:

{
"success": false,
"errorMessage": "Authentication is required",
"errorCode": "AUTHENTICATION_REQUIRED"
}
Enrichment API
{"message":"Unauthorized"}

In that case, use your OAuth credentials to request a new access token. If your OAuth credentials have expired, see Regenerate credentials above.

OAuth credentials information endpoint

Section titled OAuth credentials information endpoint

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

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.

Terminal window
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"
}'
{
"scopes": "metrics data-export speed-analysis surveys enrichment",
"permissions": {
"projects": [
{
"id": 42,
"name": "UX ANALYTICS"
}
]
}
}

Example of authentication flow

Section titled Example of authentication flow

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:

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;

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.

Some APIs add their own limits: see Data Export API limits and Metrics API limits.