Use API key authentication with the Search API

This is for:

Developer

The simplest way to authenticate HTTP requests made from a Coveo-powered search interface is to pass an API key as a bearer token in the Authorization header of each Search API and usage analytics Write API call.

This authentication method requires you to expose a Coveo API key in client-side code. As such, it’s only legitimate if both of the following conditions are satisfied:

  • The API key you use only grants minimum privileges.

  • The search interface only queries public content.

If your search interface can query secured content, you must implement the search token authentication method instead.

Step 1: Create an API key

In the Coveo Administration Console, add an API key that grants the following privileges in the desired organization:

service domain access level

Search

Execute queries

Allowed

Analytics

Analytics data

Push
Warning

Avoid granting any additional privileges to this API key, as it will be exposed in client-side code.

Make sure that you also limit the scope of this API key to a specific search hub.

A search hub is an arbitrary string that identifies the search interface from which API requests are being made. For example, if you’re creating an API key for a public documentation search page, you could use Public docs search as the search hub.

Step 2: Configure the search interface

How you set the API key in a search interface depends on the library with which the search interface is built.

Atomic library

In a search interface built with the Coveo Atomic library, set the API key when calling the initialize method on the atomic-search-interface component.

You should also set the search-hub attribute to the correct value on the atomic-search-interface component.

<head>
  <!-- ... -->
  <script type="module" src="https://static.cloud.coveo.com/atomic/v3/atomic.esm.js">
  </script>
  <link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v3/themes/coveo.css"/>
  <script>
    (async () => {
      await customElements.whenDefined('atomic-search-interface');
      const searchInterface = document.getElementById("search");
      await searchInterface.initialize({
        accessToken: "a1b2c3d4-e5f6-g7h8-i9j0-k11l12m13n14",
        organizationId: "mycoveoorganization",
      });
    })();
  </script>
  <!-- ... -->
</head>
<body>
  <atomic-search-interface id="search" search-hub="Public docs search">
    <!-- ... -->
  </atomic-search-interface>
</body>

Headless library

In a search interface built with the Coveo Headless library, set the API key and search hub in the configuration object when initializing your engine.

import { buildSearchEngine, getSampleSearchEngineConfiguration } from '@coveo/headless';
export const headlessEngine = buildSearchEngine({
  configuration: {
    search: {
      searchHub: "Public docs search"
    },
    organizationId: "mycoveoorganization",
    accessToken: "a1b2c3d4-e5f6-g7h8-i9j0-k11l12m13n14",
  }
});

JavaScript Search Framework

In a search interface built with the Coveo JavaScript Search Framework, set the API key when calling the configureCloudV2Endpoint method on the SearchEndpoint class.

You should also set the data-search-hub attribute to the correct value on the CoveoAnalytics component.

<head>
  <!-- ... -->
  <link rel="stylesheet" href="https://static.cloud.coveo.com/searchui/v2.10093/css/CoveoFullSearch.min.css" />
  <script class="coveo-script" src="https://static.cloud.coveo.com/searchui/v2.10093/js/CoveoJsSearch.Lazy.min.js"></script>
  <script src="https://static.cloud.coveo.com/searchui/v2.10093/js/templates/templates.js"></script>
  <script>
    document.addEventListener("DOMContentLoaded", () => {
      const organizationId = "mycoveoorganization";
      const apiKey = "a1b2c3d4-e5f6-g7h8-i9j0-k11l12m13n14";
      const searchInterface = document.getElementById("search");
      Coveo.SearchEndpoint.configureCloudV2Endpoint(organizationId, apiKey)
      Coveo.init(searchInterface);
    });
  </script>
  <!-- ... -->
</head>
<body>
  <div id="search" class="CoveoSearchInterface">
    <div class="CoveoAnalytics" data-search-hub="Public docs search"></div>
    <!-- ... -->
  </div>
</body>