Manage API keys

This is for:

System Administrator

A developer working on a Coveo-powered deployment may require API keys to interact with the Coveo Platform programmatically. Coveo organization administrators should understand and apply leading practices for managing API keys.

The following are typical situations in which an API key is required:

Leading practices

The following sections list the leading practices for using API keys in a number of scenarios.

Creating API keys

  • An API key should have a single purpose. For example, you should create separate API keys for your public and authenticated search pages.

  • When creating an API key, include a detailed description to help manage the key in the future. Specify with whom, when, and for what purpose you shared the API key.

  • Apply the principle of least privilege when assigning privileges to an API key. Add IP address restrictions whenever possible.

  • When selecting a preset to grant privileges to an API key, review the description of the preset to be sure that it fits the key’s purpose. If the preset requires the API key to remain private, ensure that it won’t be publicly exposed, such as in the source code of your search interface.

  • If you include an API key in the client-side code of a search interface, don’t grant it privileges other than the following:

  • You must know where and how an API key is used before editing its configuration. Removing privileges or adding IP restrictions could break the process that’s using the API key. Conversely, adding more sensitive privileges to a key that’s used in client-side code can open security holes. Therefore, it’s better to create a new API key, and then replace and disable the original key.

Using API keys

Sharing API keys

  • Communicate API keys only to legitimate stakeholders through secured channels.

API key maintenance

  • Regularly check with requesters to see if they still use the key.

  • If you have API keys that are legitimately exposed in client-side code, disable and replace them regularly to prevent unauthorized usage.

  • Delete unused API keys.

  • If you notice an API key with more privileges than needed, edit it to remove any unnecessary privileges.

  • To see if an API key is still in use, refer to the API Keys (platform-ca | platform-eu | platform-au) page and review the Last Used column. If the key isn’t used, delete it.

  • The API keys created by a user aren’t automatically deleted when their account is deleted, since that would break the processes using these API keys. Therefore, when an employee leaves your company, replace or delete the API keys they used.

Exposed keys

Warning
This section documents an upcoming feature

This section documents a new feature that’s scheduled to go live in February 2025.

API keys with sensitive privileges must remain private. They should always be protected and must never be exposed on the Internet.

Exposed API keys with sensitive privileges may pose a significant risk to the security of your Coveo organization. Unauthorized third parties can use them to carry out harmful actions or access restricted content. This can include indexed content or usage analytics data that contains personally identifiable information (PII).

To protect your organization, Coveo may deactivate exposed API keys with sensitive privileges or those showing suspicious activity.

Important

Once a key has been deactivated, it can’t be reactivated.

When an API key is flagged for deactivation, all organization administrators and the account security contact will receive an email notification explaining the reason. The key will be deactivated automatically after a set period based on the severity of the exposure or suspicious activity. Additional email notifications will be sent at the following times:

  • A certain number of days before the key is deactivated, based on the severity of the exposure or suspicious activity

  • 24 hours before deactivation

  • Immediately after deactivation

Add an API key

Before starting, review the leading practices for API keys. Follow these steps to create an API key in the Coveo Administration Console. Alternatively, developers can create API keys programmatically.

  1. On the API Keys (platform-ca | platform-eu | platform-au) page, click Add key.

  2. In the Add an API key panel, in the Configuration tab:

    1. In the Key name box, enter a name for your API key. A good name should let you easily identify the purpose of the key.

    2. In the Description box, include a detailed description to help managing the key in the future. Specify with whom, when, and for what purpose you shared the API key.

    3. Optionally, for increased security, you can control from which machines the API key is authorized to be used. Under Allowed IPs or Denied IPs, enter the IP address without spaces or enter the IP address ranges using Classless Inter-Domain Routing (CIDR) suffixes.

      Example

      You want to allow the 256 IP addresses from 192.168.1.0 to 192.168.1.255, therefore under Allowed IPs, you enter: 192.168.1.0/24.

      However, some addresses can’t be used for API keys.

  3. In the Privileges tab, grant the desired privileges to the API key. We recommend following the leading practices and using one of the privilege presets if possible.

    Note

    To prevent misuse, Coveo limits the privileges you can grant to a key. For example, you can’t create an API key combining administrative privileges (for example, View on Sources) with the privilege required to query Coveo (Allowed on Execute queries). If your implementation requires combining these privileges, create two API keys that together will have the desired privileges.

  4. When granting privileges on resources of the Search domain, you’ll see a Limit the API key scope section appear. This means you’ve selected privileges that are especially potent, therefore you must select a search hub to limit the scope of the API key.

  1. In the Access tab, specify whether each group (and API key, if applicable) in your Coveo organization can view or edit the current API key.

    For example, when creating a new API key, you could decide that members of Group A can edit its configuration, while Group B can only view it.

    For more information, see Custom access level.

  2. Click Add Key.

  3. In the Your API Key dialog that appears, click Copy to copy the key to your clipboard. Copy the key immediately, as this is the only time Coveo will display it.

  4. Paste the copied key to a safe location. If applicable, securely communicate the key to the person who requested it. If you specified IP addresses to allow or block, the configuration will take effect within a few minutes.

Disable/Enable an API key

When you disable an API key, its privileges are suspended while its configuration is kept intact. A delay is to be expected when disabling an API key.

Before starting, review the leading practices for API keys.

On the API Keys (platform-ca | platform-eu | platform-au) page, click the key you want to disable or enable, and then click More > Disable or Enable in the Action bar.

Delete an API key

It’s a good practice to delete unused API keys.

Important

Deleting an API key that’s currently in use will most probably break the application that gets services from your Coveo organization with this key. Confirm with API key stakeholders that the key is no longer used prior deleting it.

  1. On the API Keys (platform-ca | platform-eu | platform-au) page, click the key you want to delete, and then click More > Delete in the Action bar.

  2. Click Delete to confirm.

A delay is to be expected when deleting an API key.

Review API key management activities

As part of your duties, you may need to review activities related to API keys for investigation or troubleshooting purposes. To do so, in the upper-right corner of the API Keys (platform-ca | platform-eu | platform-au) page, click clock.

See Review resource activity for details on activities and alternative ways to access this information.

Limit the scope of an API key

Query routing heavily relies on the search hub value to ensure that queries are directed to the appropriate query pipeline.

When granting some privileges of the Search domain, you’ll see a Limit the API key scope section appear at the bottom of the resource list. This means that you’ve selected particularly powerful privileges that could be misused to access content by routing queries to the wrong query pipeline if the API key were exposed.

These privileges are:

Therefore, when you grant any of these privileges to an API key, you must select a search hub to limit its scope. This ensures that any query made using the API key enforces the selected search hub and is routed to the appropriate query pipeline.

Important

When creating an API key to authenticate requests for a Coveo for Commerce solution, enforcing a search hub in the API key isn’t necessary. See About Coveo for Commerce API keys.
Limit the API key scope section | Coveo Platform

About Coveo for Commerce API keys

In Coveo for Commerce scenarios, queries target the Commerce API, which automatically enforces search hub values in queries based on the commerce interface from which the query originates.

Therefore, when creating an API key for authenticating requests from a Coveo-powered Commerce interface, ensure that the API key doesn’t specify the search hub, as it’s automatically set by the Commerce API. If your index contains sensitive content that shouldn’t be visible to everyone, we recommend using source-level permissions to secure your content instead of enforcing the search hub value in the API key.

See Authenticate commerce requests for more information.

API key privilege presets

To quickly and broadly grant privileges to a group or API key, you can use the Preset dropdown menu in the Privileges tab Action bar. Your selection applies to all services.

In other words, when granting a custom access level configuration, you can save time by selecting the preset configuration closest to the access level set you want to grant, and then editing the desired privileges. The Preset dropdown menu then indicates: Custom.

Note

If you don’t have all the privileges in the preset you select, the missing privileges can’t be applied to the group. To fully apply a preset, you must have the same or a higher access level for each domain, as the access levels you can grant depend on the access level you have yourself.

For example, if you have the privilege to view all sources, you can’t grant the Edit all or Custom access levels on the Sources domain to an API key or group. Your only options are therefore View all and No access.

When granting privileges to an API key, your options in the Preset menu are:

Preset Description Grant to

Minimal access

Doesn’t grant any privileges. You can use it as a starting point to grant your API key only the privileges needed

Any API key

Admin

Allows making administrative changes to your Coveo organization just like you would in the Administration Console. This preset is useful if you’re building an application that needs to modify your organization.

Private (server-side) API keys only

Search

Allows passing the user’s identity to Coveo along with their query, so Coveo can return the items they’re allowed to see. Items with a permission model may appear in the search results, depending on whether a user is allowed to see each item.

Private (server-side) API keys only

Anonymous search

Doesn’t pass the user’s identity to Coveo along with their identity. Users aren’t required to log in to use the interface, therefore they’re all anonymous. Items with a permission model don’t appear in the search results.

API key in a public search interface (users aren’t authenticated)

Monitoring

Grants the View access level on most domains. It’s useful if you’re building external statistics dashboards for your Coveo organization, for example.

Private (server-side) API keys only

Analytics

Grants the privilege to send usage data to your Coveo organization using any identity. It’s useful if you’re building external statistics dashboards for your Coveo organization, for example.

API key in a search interface (users may or may not be authenticated)

Required privileges

The following table indicates the privileges required to view or edit elements of the API Keys (platform-ca | platform-eu | platform-au) page and associated panels (see Manage privileges and Privilege reference).

Action Service - Domain Required access level

View API keys

Organization - Activities
Organization - API keys
Organization - Groups

View

Edit API keys

Organization - Activities
Organization - Groups

View

Organization - API keys

Edit
Important

A member with the View access level on the Activities domain can access the Activity Browser. This member can therefore see all activities taking place in the organization, including those from Coveo Administration Console pages that they can’t access.