Choose and implement a search authentication method

This is for:

Developer

Any search interface that relies on the Coveo Platform must perform authenticated HTTP requests against the Search API and Coveo Usage Analytics (Coveo UA) Write API. The most commonly used methods are API key and search token authentication.

Each authentication method offers its own set of benefits and drawbacks. This article provides an overview of each method along with diagrams illustrating some typical authentication scenarios to help you choose and implement the method that best fits your needs.

Method Benefits Drawbacks

Public API Key

  • Simple implementation

  • Public API key can be used outside of intended client

  • External use of API key can result in misleading UA data

  • All users are considered anonymous

Private API Key

  • Private API key can’t be used outside of intended client

  • Complex implementation

  • All users are considered anonymous

Search Token

  • You can enforce a search hub, query pipelines, and/or query filters through the search token

  • search tokens are temporary

  • authenticated users can access secured content that they’re allowed to see

  • Complex implementation

Authentication scheme

The Search API and UA Write API both rely on the bearer HTTP authentication scheme. All HTTP requests made to these services must include an Authorization header with a valid access token (for example, API key or search token):

Authorization: Bearer <token>
Note

The preceding information is only useful if your search interface doesn’t rely on the Coveo JavaScript Search Framework, which handles all HTTP requests to the Search API and UA Write API on its own, assuming that:

API key authentication

An API key is a non-expiring access token which carries a certain set of privileges in a Coveo organization.

To implement API key authentication, create an API key with the Search - Execute queries and Analytics - Analytics data - Push privileges in the target Coveo organization, and ensure that this API key authenticates all Search API and UA Write API requests that originate from a specific search interface.

All queries that are authenticated with this API key will be performed as an anonymous user, so you should only use this method when working with public sources or items that don’t have varying levels of security.

API key authentication can be implemented in two ways:

Public API key authentication scenario

The fastest and simplest way to implement API key authentication is to expose a public API key with Search - Execute queries and Analytics - Analytics data - Edit privileges directly in the client. However, there’s no way to ensure that all of the Search API and UA Write API requests that are authenticated with this key originate from its intended search interface. This can result in the logging of invalid or incorrect UA data, among other issues.

Typical Public API Key Authentication Scenario

In a typical public API key authentication scenario:

  1. The client requests the search interface from the server.

  2. The server generates the search interface code, configures it with a public API key that has the Search - Execute queries and Analytics - Analytics data - Edit privileges, and delivers it to the client.

  3. When a query is triggered, the client calls the Search API through the search interface to execute the query, using its public API key to authenticate the HTTP request.

  4. The Search API executes the query against the index and returns only public items to the client.

  5. The client calls the UA Write API through the search interface to log a search event, using its public API key to authenticate the HTTP request.

  6. The UA Write API logs a search event for an anonymous user.

Private API key authentication scenario

Note

This is more complicated to implement than search token authentication, and it provides fewer benefits. We recommend that you use search token authentication instead.

A more complex but more robust way to implement API key authentication is to store an API key with the Search - Execute queries and Analytics - Analytics data - Edit privileges on the server, so that the search interface makes its requests against the server, which in turn makes requests to the appropriate Coveo Platform services.

With this implementation, the user can’t see the API key, so it can never be used outside of its intended search interface. Furthermore, you can implement your own throttling mechanism, which lets you better manage network traffic and avoid potential threats and issues.

Note

You can’t implement private API key authentication in a search interface that relies on the Coveo JavaScript Search Framework.
Typical Private API Key Authentication Scenario

In a typical private API key authentication scenario:

  1. The client requests the search interface from the server.

  2. The server generates the search interface code and delivers the code to the client. The returned search interface isn’t configured with an API key.

  3. When a query is triggered, the client forwards the query parameters to the server.

  4. The server, acting as a proxy, calls the Search API to execute the query against the index. The server uses a stored, private API key that has the Search - Execute queries and Analytics - Analytics data - Edit privileges to authenticate the HTTP request.

  5. The Search API executes the query against the index and returns only public items to the server, which then returns them to the client.

  6. The server, acting as a proxy, calls the UA Write API to log a search event. The server uses the same private API key used in step 4 to authenticate the HTTP request.

  7. The UA Write API logs a search event for an anonymous user.

Search token authentication

A search token is a temporary, Search API-generated JSON web token which can be used to authenticate certain Search API and UA Write API requests as a specific user.

search tokens can contain information about users, such as their display names and user groups, which may be used in query pipeline conditions. They can also be used to enforce specific search hubs, {query pipelines}, or filters on the queries they authenticate.

When a search token is used to authenticate a query, the index only returns items that the user for whom the token was generated is allowed to see. You should use this method when working with secured sources or items that have varying levels of security.

search tokens can be generated for anonymous or non-anonymous (that is, authenticated) users.

Typical anonymous search token authentication scenario

In a typical anonymous search token authentication scenario:

  1. The client requests the search interface for an anonymous user from the server.

  2. The server calls the Search API to request a search token for an anonymous user. The server uses a stored, private API key that has the privilege to impersonate (that is, the Allowed access level on the Impersonate domain) to authenticate the HTTP request (see Manage privileges).

  3. The Search API returns a search token for an anonymous user to the server.

  4. The server delivers a search interface which is configured with the search token returned in step 3.

  5. When a query is triggered, the client calls the Search API through the search interface to execute the query against the index. The client uses the search token returned in step 3 to authenticate the HTTP request.

  6. The Search API executes the query against the index and returns to the client only the query result items that anonymous users are allowed to see (that is, public items).

  7. The client calls the UA Write API through the search interface to log a search event. The client uses the search token returned in step 3 to authenticate the HTTP request.

  8. The UA Write API logs a search event for an anonymous user.

Typical non-anonymous search token authentication scenario

In a typical non-anonymous search token authentication scenario:

  1. The client requests the search interface for an authenticated user from the server.

  2. The server validates the user's credentials and then calls the Search API to request a search token for that authenticated user. The server uses a stored, private API key that has the privilege to impersonate (that is, the Allowed access level on the Impersonate domain) to authenticate the HTTP request (see Manage privileges).

  3. The Search API returns a search token containing information regarding the authenticated user to the server.

  4. The server delivers a search interface which is configured with the search token returned in step 3.

  5. When a query is triggered, the client calls the Search API through the search interface to execute the query against the index. The client uses the search token returned in step 3 to authenticate the HTTP request.

  6. The Search API executes the query against the index and returns to the client only the query result items that the authenticated user is allowed to see.

  7. The client calls the UA Write API through the search interface to log a search event. The client uses the search token returned in step 3 to authenticate the HTTP request.

  8. The UA Write API logs a search event for the authenticated user.

Note

In both search token authentication scenarios, you should implement a mechanism to ensure that the user can get a new search token when their current one expires.

Request a search token

Make a POST request to https://<ORG_ID>.org.coveo.com/rest/search/token, where <ORG_ID> is the unique identifier of your Coveo organization, to request a search token. Use an API key that has the privilege to impersonate (that is, the Allowed access level on the Impersonate domain) in the target organization to authenticate the HTTP request (see Manage privileges).

Important

If an API key has the privilege to impersonate, it should never be exposed in client-side code because this could allow users to impersonate other users and see search results that would otherwise be restricted.

Search token authentication example

A search token creation call in which you only specify the required values:

POST https://myorganizationid9sd8df7s.org.coveo.com/rest/search/token HTTP/1.1
​
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "userIds": [
    {
      "name": "john_doe@some-domain.com",
      "provider": "Email Security Provider"
    }
  ]
}

A successful request produces a JSON response containing the search token:

{
  "token": "fzKjcHdjPJKJVaJ2OjK0fzK2CI6dHJ1ZSwiZXhwIjoxNDY4Njk2NzEwLCJpYXQiOjE0lQGN..."
}
Tip
Leading practice

Use the following identity to generate search tokens for non-authenticated users:

{
  "name": "anonymous",
  "provider": "Email Security Provider",
}

Request body properties

The body of a POST request to https://<ORG_ID>.org.coveo.com/rest/search/token has the following properties:

userIds (array of RestUserId, required)

The security identities to associate with this search token. The RestUserId model has the following properties:

name (string, required)

The name of the security identity (for example, "john_doe@some-domain.com").

provider (string, required)

The security identity provider of the security identity (for example, "Email Security Provider").

type (string)

The security identity type (for example, "User").

Example

The body of a search token creation call in which you specify the type of a userIds entry.

{
  "userIds" : [
    {
      "name" : "john_doe@some-domain.com",
      "provider" : "Email Security Provider",
      "type" : "User"
    }
  ]
}

filter (string)

The query expression filter to add to all queries authenticated with this search token (see Query syntax).

You can set this property to ensure that any query authenticated with this token can only return results from a specific subset of items in the index.

Example

The body of a search token creation call in which you specify a constant query expression.

{
  "filter" : "@objecttype=Case",
  "userIds" : [
    {
      "name" : "john_doe@some-domain.com",
      "provider" : "Email Security Provider"
    }
  ]
}

pipeline (string)

The query pipeline to enforce when authenticating a query with this search token.

The query pipeline that you specify for this property takes precedence over the possible output of all other query pipeline routing mechanisms when authenticating a query using this search token.

Example

The body of a search token creation call in which you specify an enforced pipeline.

{
  "pipeline" : "Tech Support Query Pipeline",
  "userIds" : [
    {
      "name" : "john_doe@some-domain.com",
      "provider" : "Email Security Provider"
    }
  ]
}

searchHub (string)

The search hub to enforce with this search token.

The search hub is an important parameter for Coveo UA, the Coveo Machine Learning (Coveo ML) service, and query pipelines.

Example

The body of a search token creation call in which you specify an enforced searchHub.

{
  "searchHub" : "CommunitySearch",
  "userIds" : [
    {
      "name" : "john_doe@some-domain.com",
      "provider" : "Email Security Provider"
    }
  ]
}

userGroups (array of strings)

The userGroups to pass when authenticating an operation to log a search event with this search token. user groups can also be used in query pipeline statements, such as when $groups contains \"Employees\".

Example

The body of a search token creation call in which you specify userGroups entries.

{
  "userGroups" : [
    "Tech Support",
    "Employee"
  ],
  "userIds" : [
    {
      "name" : "john_doe@some-domain.com",
      "provider" : "Email Security Provider"
    }
  ]
}

userDisplayName (string)

The display name of the user with whom you want to associate this search token.

Example

The body of a search token creation call in which you specify the end-user display name.

{
  "userDisplayName" : "John Doe",
  "userIds" : [
    {
      "name" : "john_doe@some-domain.com",
      "provider" : "Email Security Provider"
    }
  ]
}

validFor (integer)

The number of milliseconds for which the search token will remain valid once it has been created.

The minimum value is 900000 (that is, 15 minutes).

The maximum and default value is 86400000 (that is, 24 hours).

Example

The body of a search token creation call in which you specify the expiration time.

{
  "validFor" : 1800000,
  "userIds" : [
    {
      "name" : "john_doe@some-domain.com",
      "provider" : "Email Security Provider",
    }
  ]
}
Note

The RestTokenParams model also exposes the salesforceCommunityUrl, salesforceFallbackToAdmin, salesforceUser,scope, and superUserToken attributes, while the RestUserId model exposes the authCookie, infos, and password attributes.

Normally, you shouldn’t manually specify values for these attributes. They’re either intended for internal use by the Coveo Platform or exposed for legacy reasons.