API Key Authentication

Build a Search UI Coveo Relevance Cloud Developer Product Documentation

The simplest way to authenticate HTTP requests made from a Coveo 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 is legitimate only 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:

Domain Access Level
Execute Queries Allowed
Analytics Data Push

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

Make sure 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 instance, if you’re creating an API key for a public documentation search page, you could use Public docs search as a search hub.

Step 2: Configure the Search Interface

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

Atomic Library

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

Be sure to 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/v2/atomic.esm.js">
  </script> 
  <link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v2/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 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 JavaScript Search Framework, set the API key when calling the configureCloudV2Endpoint method on the SearchEndpoint class.

Be sure to 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>