---
title: Implementation Guide
slug: m8tf0188
canonical_url: https://docs.coveo.com/en/m8tf0188/
collection: adobe
source_format: adoc
---
# Implementation Guide
Regardless of the [approach](https://docs.coveo.com/en/m7e92019/) you choose to build your [Coveo Platform](https://docs.coveo.com/en/186/)-powered [search interface](https://docs.coveo.com/en/2741/), follow the implementation guidelines in this article.

These guidelines apply to any website, regardless of the Content Management System (CMS) you use.
By default, the [search interfaces](https://docs.coveo.com/en/2741/) you create will display [items](https://docs.coveo.com/en/210/) from all your [Coveo organization](https://docs.coveo.com/en/185/) [sources](https://docs.coveo.com/en/246/) 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.
Minimally, these should include the following:

### The platform endpoint URL

Coveo exposes [organization-specific endpoints](https://docs.coveo.com/en/2976/) such as `<ORG_ID>.org.coveo.com` to perform queries, where `<ORG_ID>` is the unique identifier of your organization.
Under the hood, Coveo will redirect you based on your [primary deployment region](https://docs.coveo.com/en/2976/):

* USA: [platform.cloud.coveo.com](https://platform.cloud.coveo.com)
* Canada: [platform-ca.cloud.coveo.com](https://platform-ca.cloud.coveo.com)
* Australia: [platform-au.cloud.coveo.com](https://platform-au.cloud.coveo.com)
* Europe: [platform-eu.cloud.coveo.com](https://platform-eu.cloud.coveo.com)

Store the `<ORG_ID>.org.coveo.com` endpoint associated with your organization in your CMS.

### 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/), on the **[***Settings**](https://platform.cloud.coveo.com/admin/#/orgid/settings/license) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/settings/license) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/settings/license) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/settings/license))* page, under **Organization** > **Details**.

### The search hub

The [search hub](https://docs.coveo.com/en/o7qa1002/) 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/), 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#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#create-an-api-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/) 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#request-a-search-token) for that user (see [Sample usage workflow](https://docs.coveo.com/en/56#sample-usage-workflow)).

To get the full URL of your search token POST request, append `/rest/search/v2/token` to your [platform endpoint URL](#the-platform-endpoint-url).
Regardless of your data residency region, the full URL of your search token POST request is `https://<ORG_ID>.org.coveo.com/rest/search/v2/token` where `<ORG_ID>` is replaced with your unique organization ID.

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/).

## 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.leading-practice]
#### 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:


* Coveo provides code samples in [React](https://github.com/coveo/ui-kit/tree/main/packages/atomic-react), [Angular](https://github.com/coveo/ui-kit/tree/main/samples/atomic/search-commerce-angular), [Next.js](https://github.com/coveo/ui-kit/tree/master/packages/samples/atomic-next#readme), and [Vue.js](https://github.com/coveo/ui-kit/tree/master/packages/samples/vuejs/README.md) in its [Coveo ui-kit repository](https://github.com/coveo/ui-kit).

* 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/) 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/) 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/) 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/) to your search page URLs as a URI fragment and may conflict with web server configurations.