Adding and Managing API Keys

A developer may need an API key carrying specific privileges and optionally IP restrictions to allow a process to interact with your Coveo Cloud organization APIs (see Coveo Cloud Platform API).

  • A developer deploying a search interface that shows only publicly available content can ask for an API key to include in the search interface to authorize the interface to send queries and get results from your Coveo Cloud organization.

  • A developer deploying an on-premises crawler can ask for an API key to include in the crawler to authorize the crawler to use the push API to add content to a source (see Push API Usage Overview).

  • A developer asks for an API key to be able to start a source refresh from the API following the update of the content in the original indexed system.

An API key must typically be used only in server-side software processes 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 (see Privilege Management). Communicate API keys only to legitimate stakeholders through secured channels.

  • You can legitimately include an API key in the client-side code of a search interface, but only when it is limited to the following privileges (see API Key Authentication):

    • Allowed on Execute queries.

      Allows to send queries and receive search results only for content that is indexed to be available anonymously.

    • Edit on Analytics data.

      Allows to push usage analytics events.

  • Developers can create API keys programmatically (see Creating an API Key).

Do not use an API Key for a search interface in which authenticated users can find secured content. In such case, your search interface must rather use a search token that is generated for each user. Otherwise search results return only anonymously accessible content. A developer must set up a server-side mechanism to generate the search tokens using an API key (see Search Token Authentication).

Good Practices

  • Generate distinct API keys for each usage.

  • Assign to each API key only the minimum privileges needed to perform the tasks for the target usage. When possible, add IP restrictions.

  • Include a clear description (given to who, when, why, for what purpose) to help managing the key in the future.

  • Communicate the key only to the requester through a secured channel.

  • Regularly validate with requesters if they still need and use the key.

  • Disable and eventually delete API keys that are no longer used, or with uncertain purpose or user (see Disable/Enable an API Key).

  • When an employee leaves your company, delete or rotate the API keys that employee had access to (see Disable/Enable an API Key).

    The API keys created by a user are not automatically deleted by Coveo when that user is deleted, since that would break the applications using said API keys. You need to rotate those API keys manually.

  • Regularly replace limited privileges API keys legitimately exposed in client-side code with new ones, disabling the original ones to break unauthorized usage.

Access the “API Keys” Page

  1. If not already done, log in to the Coveo Cloud platform as a member of a group with the required privileges to manage API keys in the target Coveo Cloud organization.

  2. In the main menu on the left, under Organization, select API Access.

Add an API Key

Administrators can create new API keys.

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

    If the Add Key button is grayed and unresponsive, you do not have all of the required privileges to perform this action.

  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 allow you to 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 Cloud organization understand why, where, and when the key is used.

      Once you created and given away an API key to stakeholders, you have no easy way to know if, when, and from where the API key is, or has been used. The detailed information in the Description parameter might be your best information to assist in the API key life cycle management, such as determining if you can delete an API key.

      As a last resort, you can open a ticket with Coveo Support to get usage information on a specific API key by specifying the organization and the API key name.

    3. Optionally, for increased security, you can control from which machines the API key is authorized to be used.

      In the Allowed IPs and Denied IPs boxes, you can respectively whitelist or blacklist machines by entering one or more valid IP addresses for those machines (enter the IP address without spaces).

      You can also specify IP address ranges using Classless Inter-Domain Routing (CIDR) suffixes (see Classless Inter-Domain Routing).

      You want to whitelist the 256 IP addresses from 192.168.1.0 to 192.168.1.255, in the Allowed IPs parameter, enter:

      192.168.1.0/24

    Do not click Add yet!

  3. In the Privileges tab, in the menu on the left, select a service. You can then review and edit the Access Level for each privilege in the service.

    Grant only the minimal privileges required for an API key to perform Coveo Cloud organization tasks (see Privilege Management).

    To quickly and broadly grant privileges, you can use the Preset drop-down menu in the panel Action bar. Your selection applies to all services. Your options are:

    • Full access, which allows grantees to edit all resources. Full access is typically granted to administrators.

    • View all, which allows grantees to see all resources in the administration console but forbids to edit them or create new ones.

    • Minimal access, which does not grant any access level. You must then select View or Edit for the desired access levels to allow your API key to access the corresponding resources.

      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 drop-down menu should then indicate: Custom.

      • You want an API key to only be able to edit sources and fields. You therefore select the Minimal access preset configuration, select the Content services in the menu on the left, and then set the Sources and Fields privileges to Edit.

      • You want an API key to be able to edit resources of the Usage Analytics, Machine Learning, and Search services and view the resources of other services. You therefore select the Full access preset configuration and then, for the domains of the Content and Organization services, change the access levels from Edit to View.

      • If you do not have all the privileges in the preset you select, the missing privileges cannot be applied to the API key. To fully apply a preset, your user 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 (see Confirm Your Options).

    When done editing, click Save.

  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.

    Groups for which there is no drop-down menu in the Access Level column are either groups that can edit all API keys created in the organization or groups that are not allowed to see API keys at all (see Understanding Resource Access and API Keys Domain). Since these groups’ access level for any new API key is already determined, you have no decision to make regarding them in the Access tab.

    If you remove the Edit access level from all the groups of which you are a member, you will not be able to edit your API key once it is saved. Only administrators and members of other groups that have the Edit access level on this API key will be able to do so. To keep your ability to edit this API key, set the Access level to Edit for at least one of the groups of which you are a member.

  5. Click Add Key.

  6. In the Your API Key panel that appears, click Copy to copy the key to your clipboard.

    The Your Key panel is the only place and moment where you can see the key.

  7. Paste the copied key to a safe location of your choice, and if applicable, securely communicate the key to the person who requested it.

Filter API Keys

On the API Keys page, in the right section of the Action bar, type keywords in the Filter box. You can filter API keys by name, description, author, and creation date.

Edit an API Key

Administrators can modify the configuration of an existing key anytime (see Built-In Groups).

Ensure that you know if, and where, the API key is used before modifying its configuration. Removing privileges or adding IP restrictions could break the process that is using the API key in production. Adding more sensitive privileges to a key that is used in client-side code can open security holes.

Rather create a new API key, replace the original one in its legitimate usage, and disable the original API key (see Add an API Key and Disable/Enable an API Key).

  1. On the API Keys page, in the list of keys:

    • Double-click the key you want to modify.

      OR

    • Click the desired key, and then in the Action bar, click Edit.

    Grayed-out API keys are API keys for which you only have the View access level (see Understanding the Custom Access Level). You cannot edit these API keys, but you can click View in the Action bar to review their configuration.

  2. In the Edit an API Key: [Key_Name] panel, in the Configuration tab, you can modify the value of any of the parameters (see Add an API Key).

  3. Select the Privileges tab.

  4. In the menu on the left, select a service, and then, in the Access Level column, edit the access level of the privileges that you want to grant to your API key (see Privilege Management and Privilege Reference).

    When you edit the privileges of an API key, your options may vary. For each domain, the access levels you can grant depend on the access level you have yourself, as well as the level that was last saved (see Confirm Your Options).

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

    Groups for which there is no drop-down menu in the Access Level column are either groups that can edit all API keys created in the organization or groups that are not allowed to see API keys at all (see Understanding Resource Access and API Keys Domain). Since these groups’ access level for any new API key is already determined, you have no decision to make regarding them in the Access tab.

    If you remove the Edit access level from all the groups of which you are a member, you will not be able to edit your API key once it is saved. Only administrators and members of other groups that have the Edit access level on this API key will be able to do so. To keep your ability to edit this API key, set the Access level to Edit for at least one of the groups of which you are a member.

  6. Click Update.

    The API key configuration changes are immediately effective.

Disable/Enable an API Key

Once an API Key is created, you can always disable and re-enable it, meaning you can suspend and resume the granted privileges while you keep the key configuration intact.

Disabling an API key that is currently in use will most probably break the application that gets services from your Coveo Cloud organization with this key. Verify with API key stakeholders that the key is no longer used prior disabling it.

  1. On the API Keys page, in the list of keys, select 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.

    In the list of keys, a disabled key row appears in gray, with Disabled in the Status column.

Delete an API Key

Once an API Key is created, administrators can always permanently delete it.

Delete unused API keys.

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

When you are not sure if an API key is still used, it may be a better idea to first disable it, and delete it only after confirming that no service was interrupted because it was using this key (see Disable/Enable an API Key).

  1. On the API Keys page, in the list of keys, select the key you want to delete.

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

  3. In the Action bar, at the Are you sure? confirmation prompt, click Delete.

Review API Key Management Activities

The Activity panel list presents the API key management activities in the reverse chronological order. Each row represents one 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 the Activity icon (ac8-icon-clock) (see Review Events Related to Specific Coveo Cloud Administration Console Resources).

If the Activity icon is grayed and unresponsive, you do not have all of the required privileges to perform this action.

Difference with Coveo Cloud V1

API Keys can be created by members of the Administrators group or any other group that has the Can Create ability for the API Keys domain (see API Keys Domain). In Coveo Cloud V1, you need to contact Coveo OPS to create API keys.

Required Privileges

The following table indicates the privileges required to view or edit elements of the API Keys page and associated panels (see Privilege Management and Privilege Reference).

Action Service - Privilege Required access level
View API keys

Organization - Activities

Organization - API keys

Organization - Groups

Organization - Organization

View
Edit API keys

Organization - Activities

Organization - Groups

Organization - Organization

View

Organization - API keys

Edit