Authenticate via search token

This is for:


This article explains how to employ Coveo search token authentication in an SAP Commerce Cloud project. Using this authentication method provides better security, as it doesn’t require exposing the API key in the front-end code.


Make sure your configuration meets the following criteria:

Back-end configuration

Step 1: Add an OCC extension

To use search token authentication, you must add a new API to the OCC extension of your project. Whereas you can do so by building a new extension from scratch, we recommend using the prebuilt extension published on Coveo GitHub:

  1. Go to your SAP project folder.

  2. Navigate to the hybris/bin/custom folder.

  3. Clone or download the extension repository. This would create a new folder named coveocc.

  4. In the project folder, open the hybris/config/localextensions.xml file and add the coveocc extension:

    <extension name='coveocc' />
  5. Save the file.

Step 2: Build and run the server

  1. From the root of your project folder, run the following command:

    ant clean all
  2. After the command execution, navigate to the hybris/bin/platform folder.

  3. Run the script:


Step 3: Specify credentials

The Coveo credentials should be set through the graphical interface of the Backoffice Administration Cockpit.

  1. In the Administration Cockpit, go to the WCMS → Website page.

  2. In the list of websites, double-click the required website.

  3. Switch to the Administration tab.

  4. Fill in the following fields:

Local testing

To test retrieving a search token, you can use a Swagger UI that’s available when you’re running the script. By default, the Swagger UI is available at https://localhost:9002/occ/v2/swagger-ui.html, where you can find and test the getSearchToken endpoint.


By default, your local server would use ports 9001 (http) and 9002 (https).

Front-end configuration

Step 1: Add a new file

  1. Navigate to the root of your angular application (e.g., src/app folder).

  2. Create a new file, access-token.ts:

    import { environment } from "../environments/environment";
    interface GetAccessTokenOptions {
      searchHub: string;
      refresh?: boolean;
    export async function getAccessToken(options: GetAccessTokenOptions) { 1
      const { searchHub, refresh = false } = options;
      const cache = createTokenCache(searchHub)
      const cachedToken = cache.get();
      if (cachedToken && !refresh) return cachedToken;
      const token = await generateAccessToken(searchHub);
      token && cache.set(token);
      return token;
    async function generateAccessToken(searchHub: string) { 2
      const url = getCoveoAccessTokenUrl(searchHub);
      try {
        const res = await fetch(url);
        const data = await res.json();
        return data.token;
      } catch (e) {
        return '';
    function getCoveoAccessTokenUrl(searchHub: string) {
      const base = environment.occBaseUrl;
      const baseSiteId = '<YOUR_SITE_ID>'; 3
      return `${base}occ/v2/${baseSiteId}/coveo/token/${searchHub}`
    function createTokenCache(searchHub: string) { 4
      const key = `coveo-${searchHub}` 5
      const get = () => localStorage.getItem(key)
      const set = (token: string) => localStorage.setItem(key, token)
      return { get, set }
1 getAccessToken checks if there’s a token in the localStorage. If not, it calls generateAccessToken to create and retrieve a new token.
2 generateAccessToken calls the getCoveoAccessTokenUrl function which returns the URL of OCC extension that retrieves the token.
3 Saves the ID of your site into a baseSiteId variable. The site ID is the one that you configured in the Backoffice Administration Cockpit.
4 createTokenCache creates a cache object that exposes get and set methods to retrieve and store the token in the localStorage.
5 A separate cache entry is created if the searchHub value wasn’t in the localStorage.

Step 2: Update app.component.ts

Update the src/app/app.component.ts file to use the getAccessToken method:

import { getAccessToken } from './access-token';

export class AppComponent implements AfterViewInit {
  async ngAfterViewInit() {
    const searchInterface = document.querySelector('atomic-search-interface');

    const searchHub = `<YOUR_SEARCH_HUB>`;
    const accessToken = await getAccessToken({searchHub});

    if (!accessToken) {

        organizationId: '<YOUR_ORG_ID>', 1
        search: { searchHub },
        renewAccessToken: () => getAccessToken({ searchHub, refresh: true })
      .then(() => {
        const engine = searchInterface.engine;
        if (engine) {

          // ... 2

1 Pass the following parameters:
  • ID of your Coveo organization

  • Search hub

  • Access token

  • renewAccessToken method that renews the token if it’s expired. When refresh is set to true, the method ignores the cached tokens.

    See initialize.

2 You can further specify the engine configuration before executing the first search. See atomic-search-interface properties.

From now on, your storefront will use the search token to authenticate the search requests.