Authenticate commerce requests

This is for:

Developer
In this article

Your commerce interface typically make two types of requests to Coveo:

  1. Querying products via one of the product discovery solutions (search, listings, or recommendations).

  2. Logging commerce events (such as clicks and cart interactions) as visitors interact with your storefront.

The authentication method 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 or search tokens:

service domain access level

Search

Execute queries

Allowed

Analytics

Analytics data

Push

API keys

An API key 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, you can use a single API key to authenticate requests 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’s stored in your back-end. This API key will be used to generate search tokens for each user session.

    This back-end API key should have the following permissions:

    service domain access level

    Search

    Impersonate

    Allowed

    Analytics

    Impersonate

    Allowed

    Analytics

    Analytics data

    Push
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, as it’s automatically set by the Commerce API.

While it’s usually recommended to enforce the search hub 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 setting the parameter to an empty string: Search hub is "".

Empty string in Commerce API key | Coveo

If your index contains sensitive content that shouldn’t be visible to everyone, we strongly recommend using source-level permissions to secure your content instead of enforcing the search hub value in the API key.

Search tokens

If your storefront requires authentication to access content, you need to generate search tokens for the authenticated users.

To generate search tokens, create an API key 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.

Important

Ensure that your API key and generated search token doesn’t specify the search hub as this is automatically set by the Commerce API.

While it’s usually recommended to enforce the search hub 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 contains sensitive content that shouldn’t be visible to everyone, we strongly recommend using source-level permissions 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:

Availability filtering

The availability catalog object 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, you can use the filter 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:

{
  "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 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:

[...]
"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 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:

{
  "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 multi-value fields 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:

[...]
"buyer_groups": "group_1"

You can show products that are only available to a specific buyer group by using the filter 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:

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