JavaScript Search Framework Tutorial 5 - Configuring Your Own Search Endpoint

In the previous tutorials, you used a sample search endpoint to query an index containing public items.

In this tutorial, you will create a Coveo Cloud organization and provision its index by creating one or more sources. You will then configure a search endpoint against this new organization.

If you modified the ./bin/index.html page in previous tutorials, you can undo these changes by rebuilding the project.

To do so, run the following command line from the root of the tutorial project folder:

npm run build

Step 1 - Create a Coveo Cloud Organization

The easiest way to create a Coveo Cloud organization is to perform a simple HTTP POST request through Swagger UI.

  1. Access the Create organization REST endpoint.

  2. Authorize Swagger UI to execute API calls against the Coveo Cloud platform:

    1. In the top right corner of the endpoint card, if you see a red ! icon (**!**), click it.

      If you see a blue i icon (i) instead, then you have already authorized Swagger UI to execute requests. You can skip 2.b and 2.c.

    2. In the Available authorizations dialog, click Authorize. This will redirect your browser to the Coveo Cloud platform login page.

    3. Log in to the Coveo Cloud platform using one of the supported identity providers (Google, Office 365, or Salesforce). This will redirect your browser back to Swagger UI.

  3. In the name field, enter a name for your new organization, and then click Try it out.

If the request is successful (i.e., 201 Created status), the response body will contain your unique and permanent organization ID. Copy this value, as you will need it in step 4.

Step 2 - Create a Public Source

Create a new source in your organization to index public content (e.g., a shared Web source).

Step 3 - Create an API Key

Create an API key that only grants the following privileges in your organization:

Service Domain Access level
Analytics Analytics data Push
Search Execute queries Allowed

Copy the generated API key value, as you will need it in step 4.

The only time you can retrieve an API key value is when you create it.

Step 4 - Configure Your Search Endpoint

In the ./bin/index.html file, change the following line:

Coveo.SearchEndpoint.configureSampleEndpointV2();

to:

Coveo.SearchEndpoints.configureCloudV2Endpoint(
  "MY_ORGANIZATION_ID",
  "MY_API_KEY"
);

where you replace:

  • MY_ORGANIZATION_ID with the organization ID you got in step 1*.

    *If you did not copy the organization ID when you created your organization, you can still retrieve it.

  • MY_API_KEY with the API key you got in step 3.

See JavaScript Search Framework Endpoints.

If you open the search page in your browser, you should now be able to query the index of your newly created organization.

  • While the Coveo Cloud Platform is creating the index, the organization has no accessible search endpoint. Thus, until the index is ready (which may take a few minutes), any search request you send will return a 408 Request Timeout error with the NoEndPointException message.

  • Exposing an API key in client-side code is often considered a bad practice.

    However, if the index of your organization only contains public items, and the exposed API key only grants the privileges to execute queries and push usage analytics events anonymously, this simple authentication method is in fact entirely legitimate (see API Key Authentication).

Step 5 (Advanced) - Create a Secured Source

Create a new source in your organization to index secured content (e.g., a secured Google Drive for Work source).

Step 6 (Advanced) - Implement Search Token Authentication

At the moment, the search endpoint you configured in step 4 uses an API key that only allows its bearer to execute queries and push usage analytics events anonymously. Thus, your search interface currently does not allow anyone to access secured content such as the one you indexed in step 5.

To allow authenticated end users to query the secured content they should have access to, you must implement search token authentication.

The following steps summarize a typical search token authentication scenario:

  1. An end user logs in to a web server (e.g., a Salesforce organization, an IIS site, a Node.js site, etc.).
  2. The end user accesses a Coveo search interface served from the site.
  3. The web server in to which the end user has logged has information about the user identity (e.g., their email or username). This information can be mapped to a known security identity in the Coveo index.
  4. Back-end code calls the Search API to request a search token that impersonates the authenticated end user.
  5. The web server serves the search interface.

This means that the web server needs to serve the HTML content of the page and to be able to supply the search token to the JavaScript code that will configure the search endpoint.

  • In a Salesforce organization, you could print the token using Apex code in the Visualforce page.

  • With an IIS website, this could be done with ASP.NET code.

  • In a Node.js website, this could be done with a templating engine, or by providing a back-end call that the JavaScript code could access using an XMLHTTPRequest.

For further explanations and examples, see Search Token Authentication.

What’s Next?

You should now proceed to JavaScript Search Framework Tutorial 6 - Result Templates.