Manage API Keys

A developer working on a Coveo deployment may require one or more API keys to interact with the Coveo Platform 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

  • When assigning privileges to an API key, apply the principle of least privilege. When possible, add IP restrictions.

  • When creating an API key, 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.

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

  • 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 is better to create a new API key, and then to replace and disable the original key.

  • Regularly validate with requesters whether they still use the key.

  • Delete unused API keys.

  • If you’re not sure whether an API key is still being used, try disabling it. Delete it after confirming that no service has been interrupted because it was using this 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.

  • An API key should have a single purpose.

  • 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 determined by source permissions 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.

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

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

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.

  1. On the API Keys page, click Add key.

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

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

    2. In the Description box, enter any detailed information that will help you or other administrators of your Coveo organization understand why, where, and by whom the key is used. This is crucial to keep track of your API keys.

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

      You want to allow the 256 IP addresses from 192.168.1.0 to 192.168.1.255, so under Allowed IPs, you enter:

      192.168.1.0/24

  3. In the Privileges tab, grant the desired privileges to the API key. It is a good practice to apply the principle of least privilege. See Navigate the Privileges Tab and Determine the Privileges to Grant for details on this process.

  4. In the Access tab, use the Access level drop-down menus to determine whether each group in your organization can view or edit your API key.

  5. Click Add Key.

  6. 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.

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

  1. On the API Keys page, click the key you want to disable or enable.

  2. In the Action bar, click More, and then in the drop-down menu, select Disable or Enable.

Delete an API Key

It is 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.

  1. On the API Keys page, click the key you want to delete.

  2. In the Action bar, click More, and then select Delete.

  3. Click Delete to confirm.

Review API Key Management Activities

The Activity panel list presents the API key management activities in the reverse chronological order. Each row represents an activity, indicating when it occurred, the name of the affected API key, what was done (created, updated, deleted), and the state (enabled, disabled).

You can review the creation, change, and deletion history of your API keys. To do so, on the API Keys page, click Activity. See Review Events Related to Specific Coveo Administration Console Resources for details on activities.

Required Privileges

The following table indicates the privileges required to view or edit elements of the API Keys 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
Recommended Articles