Manage API keys
Manage API keys
A developer working on a Coveo deployment may require one or more API keys to interact with Coveo programmatically. Coveo organization administrators should therefore understand and apply leading practices when it comes to managing API keys.
The following are typical situations where an API key is required:
-
A developer is working on a search interface that can show public and secured content. They need an API key to implement search token authentication.
-
A developer is building a custom connector that uses the Push API to index content behind a firewall. They need an API key to authenticate their Push API calls.
Leading practices
Creating API keys
-
An API key should have a single purpose.
-
When creating an API key, include a detailed description to help manage the key in the future. Specify whom you share the API key with, when, and for what purpose.
-
When assigning privileges to an API key, apply the principle of least privilege. When possible, add IP restrictions.
-
If you include an API key in the client-side code of a search interface, don’t grant it other privileges than the following:
-
Allowed on Execute queries
-
Push on Analytics data
-
-
Ensure that you know if and where 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
-
An API key must typically be used only in a server-side software process where only a limited number of authorized people can see the API key. This is particularly important when the API key carries sensitive privileges that could be exploited by malicious users.
-
A search interface whose scope includes content to which user access is based on the repository’s permission system should use a search token generated for each user rather than an API key. The search interface developer must set up a server-side mechanism to generate the search tokens using an API key.
Sharing API keys
-
Communicate API keys only to legitimate stakeholders through secured channels.
API key maintenance
-
Regularly validate with requesters whether they still use the key.
-
If you have API keys legitimately exposed in client-side code, disable and replace them with new ones regularly to prevent unauthorized usage.
-
Delete unused API keys.
-
If you’re not sure whether an API key is still being used, disable the key to see if any services are interrupted. If not, you can [delete] the key.
-
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 that they used.
Add an API key
Follow these steps to create an API key in the Coveo Administration Console. Alternatively, developers can create API keys programmatically.
Before you start, ensure you are aware of the leading practices regarding API keys.
-
On the API Keys (platform-ca | platform-eu | platform-au) page, click Add key.
-
In the Add an API Key panel, in the Configuration tab:
-
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.
-
In the Description box, include a detailed description to help managing the key in the future. Specify whom you share the API key with, when, and for what purpose.
-
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.
ExampleYou want to allow the 256 IP addresses from
192.168.1.0
to192.168.1.255
, therefore under Allowed IPs, you enter:192.168.1.0/24
.Some addresses however can’t be used for API keys.
-
-
In the Privileges tab, grant the desired privileges to the API key. We recommend following the leading practices.
NoteTo prevent misuse, Coveo limits the privileges you can grant to a key. For example, you can’t create an API key combining administrative privileges (e.g., 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 which, together, will have the desired privileges.
-
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.
-
In the Access tab, set 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.
See Custom access level for more information.
-
Click Add Key.
-
In the Your API Key dialog that appears, click Copy to copy the key to your clipboard. Copying your key right now is crucial since this is the only time Coveo will display it.
-
Paste the copied key to a safe location, and if applicable, securely communicate the key to the person who requested it. If you specified IP addresses to allow or block, this configuration will be effective within a couple minutes.
Disable/Enable an API key
When you disable an API key, its privileges are suspended while its configuration is kept intact.
Before you start, ensure you are aware of the leading practices regarding 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.
|
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. |
-
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.
-
Click Delete to confirm.
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 top-right corner of the API Keys (platform-ca | platform-eu | platform-au) page, click .
See Review resource activity for details on activities and alternative ways to access this information.
Limit the scope of an API key
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 you’ve selected privileges that are especially potent, and that, should your API key be disclosed, could be misused to access your content and/or bypass the permission system.
These privileges are:
-
Execute queries: Allowed
-
Impersonate: Allowed
-
View all content: Allowed
Therefore, when you grant any of these privileges to an API key, you must select a search hub to limit its scope.

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 |
|
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 Administration Console pages that they can’t access. |