Authentication
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.
OAuth2 authentication
Section titled OAuth2 authenticationThe 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.
Create credentials
Section titled Create credentialsYou 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.
- Go to the account or project level, open the API Credentials tab, and start creating new credentials.
- Name your credentials and, optionally, restrict them to a list of allowed IP addresses (IPv4 or IPv6). By default, any IP can use them.
- Confirm to create them. A pop-up displays your generated
client_idandclient_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.
Regenerate credentials
Section titled Regenerate credentialsRegenerating credentials invalidates the previous client_secret for that connection, so update any application that
still uses it.
- Go to the API Credentials tab, open the ... menu next to the credentials, and select Regenerate credentials.
- Confirm the action.
- Copy and store the new
client_secretfrom the pop-up: you won't be able to view or recover it afterward.
Edit credentials
Section titled Edit credentialsEditing credentials lets you change their name, description, or IP allowlist without generating a new client_secret
— the existing credentials keep working.
- Go to the API Credentials tab, open the ... menu next to the credentials, and select Edit credentials.
- Update the name, description, or allowed IPs, then save your changes.
Revoke credentials
Section titled Revoke credentialsRevoking credentials deletes them permanently and immediately breaks any application still using them.
- Go to the API Credentials tab, open the ... menu next to the credentials, and select Revoke credentials.
- Confirm the action. The credentials are removed from the list and can no longer be used to query Contentsquare's public APIs.
Authentication endpoint
Section titled Authentication endpointPOST https://api.contentsquare.com/v1/oauth/token
Request parameters
Section titled Request parametersclient_idstring RequiredThe OAuth
client_idgenerated from the Contentsquare console.client_secretstring RequiredThe OAuth
client_secretgenerated from the Contentsquare console.grant_typestring RequiredAlways set it to
"client_credentials", as required by the OAuth 2.0 standard.scopestring RequiredThe scope to request, depending on which API you want to query:
enrichment,data-export,metrics,surveys, orspeed-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 isenrichment.project_idintegerRequired only if you use account-level OAuth credentials, to specify which project of the account you want to target.
integration_idintegerRequired only if you use the
enrichmentscope. This is the ID of the target integration. This ID is provided by Contentsquare when installing the integration on a project.
Scopes
Section titled Scopes| API | scope | Extra request parameters | Base URL (endpoint) |
|---|---|---|---|
| Data Export | data-export | project_id* | https://api.contentsquare.com |
| Metrics | metrics | project_id* | https://api.contentsquare.com |
| Responses | surveys | project_id* | https://api.contentsquare.com |
| Enrichment | enrichment | integration_id | https://enrichment-api.{cloud}.contentsquare.com |
| 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
Section titled Request and response examplescurl --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"}Errors
Section titled ErrorsIf 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"}401withinvalid_client: theclient_id/client_secretpair 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.400withinvalid_request: a parameter is missing or malformed. Theerror_descriptionnames it, for exampleparameter client_secret is invalid.403: the credentials have no access to the requestedproject_idorscope.
Refresh your access token
Section titled Refresh your access tokenOnce 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"}{"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 endpointPOST https://api.contentsquare.com/v1/oauth/me
Request parameters
Section titled Request parametersclient_idstring RequiredThe OAuth
client_idgenerated from the Contentsquare console.client_secretstring RequiredThe OAuth
client_secretgenerated from the Contentsquare console.
Request example
Section titled Request examplecurl --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
Section titled Response example{ "scopes": "metrics data-export speed-analysis surveys enrichment", "permissions": { "projects": [ { "id": 42, "name": "UX ANALYTICS" } ] }}Example of authentication flow
Section titled Example of authentication flowEnd-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 endpointsconst 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 exampleconst dataExportApiEndpointResponse = await fetch(`${baseURL}/v1/exports`, { headers: { Authorization: `Bearer ${accessToken}` },});const dataExportApiEndpointauthJsonData = await dataExportApiEndpointResponse.json();const exports = dataExportApiEndpointauthJsonData.payload;End-to-end authentication flow that first retrieves an access token and then uses it to retrieve the list of segments 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: "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 endpointsconst 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 exampleconst metricsApiEndpointResponse = await fetch(`${baseURL}/v1/segments`, { headers: { Authorization: `Bearer ${accessToken}` },});const metricsApiEndpointauthJsonData = await metricsApiEndpointResponse.json();const segments = metricsApiEndpointauthJsonData.payload;End-to-end authentication flow that first retrieves an access token and then uses it to list the surveys of 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: "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 endpointsconst accessToken = authJsonData.access_token;const baseURL = authJsonData.endpoint;// Using the access token and base URL to list the surveys of a project in this exampleconst responsesApiEndpointResponse = await fetch(`${baseURL}/v1/public/projects/42/surveys`, { headers: { Authorization: `Bearer ${accessToken}` },});const responsesApiEndpointauthJsonData = await responsesApiEndpointResponse.json();const { results, next_cursor } = responsesApiEndpointauthJsonData;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:
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 endpointsconst accessToken = authJsonData.access_token;const baseURL = authJsonData.endpoint;// Using the access token and base URL to send a batch of enrichment dataawait 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 for the full payload.
End-to-end authentication flow that first retrieves an access token and then uses it to retrieve the list of monitorings 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: "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 endpointsconst 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 exampleconst 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
Section titled LimitsAll Contentsquare APIs share the following limits:
- 10 concurrent requests maximum per project. Beyond that, requests fail with a
429error. - 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.