---
updatedAt: 2025-11-26T17:42:48.000Z
agentTools:
  projectIndex: https://docs.constructor.com/llms.txt
---

# Authentication

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](https://docs.constructor.com/reference/v1-search-get-search-results), [Browse](https://docs.constructor.com/reference/v1-browse-get-browse-results), [Recommendations](https://docs.constructor.com/reference/v1-recommendations-get-pod-results), [Autocomplete](https://docs.constructor.com/reference/autocomplete-autocomplete-results) or the [AI Shopping Agent](https://docs.constructor.com/reference/v1-asa-retrieve-intent), are intended to serve users of our customers and do not require authentication.

In contrast, private endpoints, which are used to manage [catalog](https://docs.constructor.com/reference/v1-catalog-create-or-replace-catalog) data or to configure various aspects of Constructor (like [facets](https://docs.constructor.com/reference/configuration-facets), [sort options](https://docs.constructor.com/reference/configuration-sort-options), [redirects](https://docs.constructor.com/reference/v1-redirects-retrieve-redirect-rule), 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](https://swagger.io/docs/specification/v3_0/authentication/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](https://app.constructor.io/dashboard/integration/api_tokens) under the *Integration > API Integration* section. Note that all API requests must be made over HTTPS.

```curl curl
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](https://swagger.io/docs/specification/v3_0/authentication/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](https://docs.constructor.com/docs/using-the-constructor-dashboard-monitoring-integration-status-generate-and-manage-api-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:

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

```json
{
  "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.**

<br />