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, create an API key using the Anonymous search template.

Warning

Browser code can use only an API key created from the Anonymous search template for public content, or a search token generated on your server. Never expose an API key created from a template tagged Must remain private.

You should also select a search hub when you configure this API key.

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.57.3/atomic.esm.js">
  </script>
  <link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v3.57.3/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>