---
title: Authenticate commerce requests
slug: o8ld0051
canonical_url: https://docs.coveo.com/en/o8ld0051/
collection: coveo-for-commerce
source_format: adoc
---
# Authenticate commerce requests
Your commerce interface typically make two types of requests to Coveo:

. Querying products via one of the [product discovery solutions](https://docs.coveo.com/en/o53d9587/) (search, listings, or recommendations).

. [Logging commerce events](https://docs.coveo.com/en/3188/) (such as clicks and cart interactions) as [visitors](https://docs.coveo.com/en/nbub9475/) interact with your [storefront](https://docs.coveo.com/en/p33g0410/).

The [authentication method](https://docs.coveo.com/en/n3ge4046/) to use depends on whether your storefront is publicly accessible to anyone on the internet or requires users to authenticate before accessing content.

Both types of requests require the following privileges, which can be granted using [API keys](#api-keys) or [search tokens](#search-tokens):

[%header,cols="~,~,~"]
|===
|[service](https://docs.coveo.com/en/2821/)
|[domain](https://docs.coveo.com/en/2819/)
|[access level](https://docs.coveo.com/en/2818/)

|Search
|[Execute queries](https://docs.coveo.com/en/1707#execute-queries-domain)
|Allowed

|Analytics
|[Analytics data](https://docs.coveo.com/en/1707#analytics-data-domain)
|Push
|===

## API keys

An [API key](https://docs.coveo.com/en/105/) is a key that can be used to authenticate requests to the Coveo Platform for both querying products and logging commerce events depending on which permissions it has.

How you use your API keys depends on whether your storefront is completely public or allows users to be authenticated.

* If your storefront doesn't require authentication, create an API key using the **Anonymous search** [API key template](https://docs.coveo.com/en/1718#api-key-templates) to generate an API key with the required permissions.
This API key would be shared between all users of your storefront and can be publicly exposed in the client-side code.

* If your storefront requires authentication, you must use search tokens to authenticate the requests.
To generate these search tokens, you first need to create a secure API key that will be stored in your back-end.
This API keys will be used to generate search tokens for each user session.
Use the **Authenticated search** [API key template](https://docs.coveo.com/en/1718#api-key-templates) to generate an API key with the required permissions.

> **Important**
>
> When creating an API key to authenticate requests for a Coveo for Commerce solution, ensure that your API key doesn't specify the [search hub](https://docs.coveo.com/en/1342/), as it's automatically set by the Commerce API.
> 
> While it's usually recommended to enforce the [search hub](https://docs.coveo.com/en/1342/) value in the API key to protect the security of content that shouldn't be visible to everyone, this isn't required for Coveo for Commerce solutions, since products are typically accessible to all visitors.
> 
> This can be done by leaving the **Search hub** section empty when creating the API key.
> 
> ![Empty string in Commerce API key | Coveo](:https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/api-key-commerce.png)
> 
> If your [index](https://docs.coveo.com/en/204/) contains sensitive content that shouldn't be visible to everyone, we strongly recommend using [source-level permissions](https://docs.coveo.com/en/1779#same-users-and-groups-as-in-your-content-system) to secure your content instead of enforcing the [search hub](https://docs.coveo.com/en/1342/) value in the API key.

## Search tokens

If your storefront requires authentication to access content, you must generate [search tokens](https://docs.coveo.com/en/56/) for the authenticated users.

To generate search tokens, [create an API key](#api-keys) and use it to generate search tokens for each user session.
This approach keeps the API key secure in your back-end and only exposes the search token to the authenticated client.

For more details on how to generate search tokens, see [Search Tokens](https://docs.coveo.com/en/56/).

> **Important**
>
> Ensure that your API key and generated search token doesn't specify the [search hub](https://docs.coveo.com/en/1342/) as this is automatically set by the Commerce API.
> 
> While it's usually recommended to enforce the [search hub](https://docs.coveo.com/en/1342/) value to protect the security of content that shouldn't be visible to everyone, this isn't required for Coveo for Commerce solutions, as products are typically accessible to all visitors.
> 
> If your [index](https://docs.coveo.com/en/204/) contains sensitive content that shouldn't be visible to everyone, we strongly recommend using [source-level permissions](https://docs.coveo.com/en/1779#same-users-and-groups-as-in-your-content-system) to secure your content.

### Filtering content using search tokens

In some cases, such as in B2B scenarios where users should only see content they have access to (for example, price lists or products), you can filter the content that users can access by leveraging search token authentication.

There are different mechanisms that can be used to filter content using search tokens, but this section discusses the three most common ones:

* Using the [availability](https://docs.coveo.com/en/mc7e9096/) [catalog object](https://docs.coveo.com/en/ncig0154/)

* Using dictionary fields

* Using multi-value fields

#### Availability filtering

The [availability](https://docs.coveo.com/en/mc7e9096/) [catalog object](https://docs.coveo.com/en/ncig0154/) determines whether a given customer can purchase a given product.
For example, you can have products that are available to all users, to users in a specific region, or to users with a specific role.

You can specify availabilities in search tokens to filter the products that users can access.
To do so, assuming that you use the recommended `ec_availability_id` metadata to uniquely identify [availability channels](https://docs.coveo.com/en/mc7e9096/), you can use the [`filter`](https://docs.coveo.com/en/56#filter-string-optional) property in the search token to filter products based on the user's accessible `ec_availability_id` field.

**Example**

In a B2B scenario, you have a list of products that are only available to `Barca` customers.
Therefore, when requesting a search token for a user that belongs to the `Barca` group, the payload should include a filter on the `ec_availability_id` field to only return products that are available to the `Barca` group, as follows:

```json
{
  "filter": "@ec_availability_id=Barca", <1>
  "userIds": [
    {
      "user_id": "alex@barca.com",
      "provider": "Email Security Provider",
      "type": "User"
    }
  ]
}
```

<1> The `filter` property filters the products based on the `ec_availability_id` a user has access to.

#### Dictionary fields filtering

If you use [dictionary fields](https://docs.coveo.com/en/2036/) to categorize products based on different criteria, you can leverage these fields in search tokens to filter the field values that users are entitled to.

For example, in your product data, you can have a dictionary field called `price_list` for which the values provide different prices depending on the user's group, as follows:

```json
[...]
"price_list": {
    "group_1": "22.00",
    "group_2": "21.50",
    "group_3": "21.00"
}
```

You can show the right dictionary field value to the user by using the [`dictionaryFieldContext`](https://docs.coveo.com/en/56#filter-string-optional) property in the search token payload.
Using this property, you can specify the dictionary field values that should be returned in the search results.

**Example**

In a B2B scenario, you have a special price list for customers of the `group_1` group.
Therefore, when requesting a search token for a user that belongs to the `group_1` group, the payload should include the `dictionaryFieldContext` property to only return the `price_list` dictionary field values that are available to the `group_1` group, as follows:

```json
{
  "dictionaryFieldContext": {
    "price_list": "group_1" <1>
  },
  "userIds": [
    {
      "user_id": "alex@barca.com",
      "provider": "Email Security Provider",
      "type": "User"
    }
  ]
}
```
<1> The `dictionaryFieldContext` property filters the products based on the `price_list` dictionary field values a user has access to.

#### Multi-value fields filtering

If you use fields with the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) enabled to categorize products based on different criteria, you can leverage these fields in search tokens to ensure that users only see the products they're entitled to.

For example, in your product data, you can have a multi-value field called `buyer_groups` that you use to tag products based on the buyer groups they belong to, as follows:

```json
[...]
"buyer_groups": "group_1"
```

You can show products that are only available to a specific buyer group by using the [`filter`](https://docs.coveo.com/en/56#filter-string-optional) property in the search token payload.

Using this property, only products that are tagged with the buyer group the user belongs to will be returned in the search results.

**Example**

In a B2B scenario, you have products that are categorized based on the buyer group they belong to.
Therefore, when requesting a search token for a user that belongs to the `group_1` group, the payload should include a filter on the `buyer_groups` multi-value field to only the products that are tagged with the `group_1` value, as follows:

```json
{
  "filter": "@buyer_groups=group_1", <1>
  "userIds": [
    {
      "user_id": "alex@barca.com",
      "provider": "Email Security Provider",
      "type": "User"
    }
  ]
}
```
<1> The `filter` property filters the products based on the `buyer_groups` multi-value field values a user has access to.