Authentication
OAuth2 authentication
Section titled OAuth2 authenticationThe 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_ACCESS_TOKEN
).
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 Metrics 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
Refresh your access token
Section titled Refresh your access tokenOnce 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:
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.
Authentication endpoint
Section titled Authentication endpointPOST 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
You should use
"metrics"
.
If needed, you can specify a list of several scopes to get a token that can query several APIs (for example “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 isenrichment
. -
project_id integer
Required only if you use account-level OAuth credentials, to specify which project of the account you want to target.
Request example
Response example
Example of authentication flow
Section titled Example of authentication flowBelow 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 segments on a project:
OAuth credentials information endpoint
Section titled OAuth credentials information endpointPOST 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.