Our API methods are categorized into two types based on authentication requirements: public endpoints that do not require authentication, and private endpoints that do.

Public endpoints, such as those used for Search, Browse, Recommendations, Autocomplete or the AI Shopping Agent, are intended to serve users of our customers and do not require authentication.

In contrast, private endpoints, which are used to manage catalog data or to configure various aspects of Constructor (like facets, sort options, redirects, etc.), require an authentication token. Most private endpoints accept either Basic or Bearer authentication, allowing you to choose whichever method fits your use case.

Basic authentication

HTTP Basic authentication is supported by most authenticated API routes. To authenticate, provide your API token as the username in the Basic Auth header of every request - no password should be specified.

You can obtain an API token from the customer dashboard under the Integration > API Integration section. Note that all API requests must be made over HTTPS.

curl -sS -X GET
  -H "Content-Type: application/json"
  -u "[API token]:"
  "https://ac.cnstrc.com/v2/items?key=[API key]"

If authentication fails, the API will respond with a 401 Unauthorized status code.

Bearer authentication

HTTP Bearer authentication is also supported by most authenticated API routes, where a token is supplied with the request. You can generate and manage Bearer tokens via the Customer Dashboard.

To authenticate with the new token you will need to provide the new token in the following format: Authorization: Bearer <token>

Permissions and scopes

When using the new authentication token, it must include explicit permissions. If the token lacks the required permissions, requests will be denied with a 403 Forbidden status code.

A permission is defined using the following structure:

{
  "scope": "scope",
  "operation": "r | w | rw",
  "resources": ["resource-1", "resource-2", ...]
}

• scope: A string representing a specific endpoint or group of endpoints.
• operation: The level of access granted for the scope. Possible values are: read (r), write (w) or read and write (rw).
• resources: A list of strings that define a subset of data to which the permission applies.

To find out which scopes are required for a given endpoint, please refer to the API reference. Required scopes are listed in the format scope(r), where r indicates the required access level (e.g., r, w, or rw).

Currently, you can specify API keys as resources to grant a token access to specific keys.

{
  "scope": "scope",
  "operation": "r",
  "resources": ["<API key>"]
}

Difference between API key and API token

An API key is a public identifier used to specify an index in API calls, while the API token is used for authentication and authorization.

The API token used for authorization is sensitive information, and therefore must be kept confidential.