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.