---
title: Implementation guide
slug: n3u80165
canonical_url: https://docs.coveo.com/en/n3u80165/
collection: coveo-for-sitecore-v5
source_format: adoc
---
# Implementation guide

After [choosing your technology](https://docs.coveo.com/en/n3tg6058.md), use this guide to implement your [Coveo Platform](https://docs.coveo.com/en/186.md)-powered [search interface](https://docs.coveo.com/en/2741.md).
While the guidelines are technology-agnostic, this article focuses on the recommended Atomic library solution.

By default, the [search interfaces](https://docs.coveo.com/en/2741.md) you create will display [items](https://docs.coveo.com/en/210.md) from all your [Coveo organization](https://docs.coveo.com/en/185.md) [sources](https://docs.coveo.com/en/246.md) in the search results.

The following diagram gives a high-level view of the server-side tasks you must code to build a functional search interface.
The diagram also shows the client-side event flow before the search page is ready for use.
More details about specific pieces of the implementation are provided further below.

![General guidelines when building a search interface in a website | Coveo](https://docs.coveo.com/en/assets/images/build-a-search-ui/integrating-search-interface-architecture.png)

## Retrieve the Coveo-related configuration

To link a search interface to your Coveo organization, configuration is required.
You want to store the configuration parameters in your CMS.
At a minimum, store the following values:

### The Search endpoint URL

Coveo exposes [organization-specific endpoints](https://docs.coveo.com/en/mcc80216.md) to perform Search API queries.
Store the endpoint that matches your organization type in your CMS:

* `https://<ORG_ID>.org.coveo.com` for a standard Coveo organization.

* `https://<ORG_ID>.orghipaa.coveo.com` for a [HIPAA organization](https://docs.coveo.com/en/1853.md).

`<ORG_ID>` is the unique identifier of your organization.

### The Coveo organization ID

Calls to the Coveo APIs require that you specify your organization ID.
This information may be found in the [Coveo Administration Console](https://docs.coveo.com/en/183.md), on the **Settings** page, under **Organization** > [**Details**](https://platform.cloud.coveo.com/admin/#/orgid/settings/organization/details) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/settings/organization/details) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/settings/organization/details) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/settings/organization/details)).

### The search hub

The [search hub](https://docs.coveo.com/en/o7qa1002.md) is an important piece of information that your search interface should send to the Search API in its queries.
When creating [your Authenticated search API key](#the-authenticated-search-api-key), you should limit the scope of the key to this search hub.

> **Note**
>
> If you're using the [Coveo Atomic library](https://docs.coveo.com/en/lcdf0264.md), you'll set the search hub value in your search interface using the `search-hub` attribute of the [atomic-search-interface](https://static.cloud.coveo.com/atomic/v3/storybook/index.html?path=/docs/atomic-search-interface\--docs) component.

### The Authenticated search API key

On the [**API Keys**](https://platform.cloud.coveo.com/admin/#/orgid/organization/api-access/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/organization/api-access/)) page, create an API key using the **Authenticated search** [template](https://docs.coveo.com/en/1718.md#api-key-templates).

![Creating an API key for authenticated search | Coveo](https://docs.coveo.com/en/assets/images/build-a-search-ui/authenticated-search-key-purpose.png)

> **Important**
>
> To adhere to leading security practices, you should restrict the use of the API key to a specific search hub and defined IP addresses.
>
> ![Limiting the API key scope](https://docs.coveo.com/en/assets/images/build-a-search-ui/limit-api-key-scope.png)
>
> See [Create an Authenticated search key](https://docs.coveo.com/en/1718.md#create-an-authenticated-search-key) for more information.

The Authenticated search API key will be used to generate a [search token](#generate-a-search-token).

> **Warning**
>
> Never expose an Authenticated search API key in client-side code.

## Retrieve the user context

Retrieve the user context to [generate a search token](#generate-a-search-token) for the corresponding [security identity](https://docs.coveo.com/en/240.md) in your Coveo organization.

## Generate a search token

Your server-side code will use the [Authenticated search API key](#the-authenticated-search-api-key) from your configuration storage and the security identity to [request a search token](https://docs.coveo.com/en/56.md#request-a-search-token) for that user (see [Sample usage workflow](https://docs.coveo.com/en/56.md#sample-usage-workflow)).

To get the full URL of your search token POST request, append `/rest/search/v2/token` to your [Search endpoint URL](#the-search-endpoint-url):

* `https://<ORG_ID>.org.coveo.com/rest/search/v2/token` for a standard organization.
* `https://<ORG_ID>.orghipaa.coveo.com/rest/search/v2/token` for a [HIPAA organization](https://docs.coveo.com/en/1853.md).

`<ORG_ID>` is the unique identifier of your organization.

Your Coveo search library client-side code will use the search token to authenticate requests to the Coveo Search API.

> **Warning**
>
> Never expose an Authenticated search API key in client-side code.
> The generated search token can be exposed as it's scoped to the current user context.

> **Note**
>
> Search token authentication is only one of several methods you can use to [authenticate calls to the Coveo REST API](https://docs.coveo.com/en/102.md).

## Serve the Coveo-powered search page

Write your search page HTML and JavaScript sections, following the reference documentation of the search interface library you chose to use.

> **Tip**
>
> The Coveo Atomic library is the recommended approach to building your Coveo-powered search pages in websites.
> See the following resources to build an Atomic search page:
>
>
> * Executing `npm create @coveo/ui` is the recommended way to start a new [Atomic](https://docs.coveo.com/en/lcdf0264.md) project.
> This command generates a basic search page that runs against sample data.
> No authentication required.
>
> * For Atomic library reference documentation, see [Use the Atomic library](https://docs.coveo.com/en/atomic/latest/).

### Example

You have decided to use Coveo Atomic as your search interface library.
You can use your stored and generated constants as follows:

* [Search hub](#the-search-hub): Use this value for the `atomic-search-interface` component [`searchHub`](https://docs.coveo.com/en/atomic/latest/reference/components/atomic-search-interface#properties) property.

* [Search token](#generate-a-search-token) and [Coveo organization ID](#the-coveo-organization-id): Use these values in the [searchInterface `initialize` method](https://docs.coveo.com/en/atomic/latest/usage#use-components-to-create-a-search-interface), for the `accessToken`, `organizationId`, and [`organizationEndpoints`](https://docs.coveo.com/en/mcc80216.md) arguments, as follows:

  ```JavaScript
  <script>
    (async () => {
      await customElements.whenDefined("atomic-search-interface");
      const searchInterface = document.querySelector("#search");

      await searchInterface.initialize({
        accessToken: "eyJhbGciOiJIUzI1NiJ9eyM2OCI6dHJ1ZSwib3JnYW5pemF0aW9uIjoibWR0ZXN0MjIyc2VySWRzIm92a...",
        organizationId: "mtest211p9s2x",
      });
      searchInterface.executeFirstSearch();
    })();
  </script>
  ```

  For a HIPAA organization, add the `environment: "hipaa"` property to the initialization configuration, as follows:

  ```javascript
  await searchInterface.initialize({
    accessToken: "eyJhbGciOiJIUzI1NiJ9eyM2OCI6dHJ1ZSwib3JnYW5pemF0aW9uIjoibWR0ZXN0MjIyc2VySWRzIm92a...",
    organizationId: "mtest211p9s2x",
    environment: "hipaa",
  });
  ```

## When the search interface is ready for use

Once initialized, the search interface listens and reacts to events on its components.
For example, if you type a query in the search box and then click the submit button, the search interface component will call the Coveo Search API using the search token. The Search API response will be a list of results.

By default, the [`atomic-search-interface`](https://static.cloud.coveo.com/atomic/v3/storybook/index.html?path=/docs/atomic-search-interface\--docs) component automatically sends [Coveo Analytics events](https://docs.coveo.com/en/260.md) to the region-specific analytics endpoint along with every search call.

> **Note**
>
> With the JavaScript Search Framework, add the [`Analytics` component](https://docs.coveo.com/en/365.md) to record search interface events.

Be aware that the `atomic-search-interface` component [`reflectStateInUrl`](https://docs.coveo.com/en/atomic/latest/reference/components/atomic-search-interface#properties) property default value is `true`.
This setting appends the [basic query expression (`q`)](https://docs.coveo.com/en/178.md) to your search page URLs as a URI fragment and may conflict with web server configurations.