Manage API keys

This is for:

System Administrator

Developers working on Coveo-powered deployments may require API keys to interact programmatically with the Coveo Platform. 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:

API key templates

The Coveo Administration Console uses templates to grant privileges to API keys. Most of these templates are predefined bundles of privileges that are suitable for common use cases.

The Custom template doesn’t have any predefined privileges, so you can set whichever ones you need, with some limitations. This flexibility comes with added risks, so you should consult the leading practices before you use it.

Each template is tagged with a privacy level: Can be public or Must remain private. Templates tagged as Must remain private carry sensitive privileges that could be exploited by malicious users.

Template Privacy Description Privileges

Anonymous search

Can be public

To query for public content and send usage analytics data on a search interface that doesn’t require any form of authentication. Can be embedded directly in the search interface.

Authenticated search

Must remain private

To support authenticated queries and send usage analytics data. This key must be stored on a secured backend and used to generate search tokens based on the security identity of the logged-in user.

Usage analytics

Can be public

Use this key to send usage analytics data to your Coveo organization using any security identity.

Search pages

Can be public

Use this key when implementing Coveo-hosted search pages.

Custom

Must remain private

Create a custom combination of privileges. We recommend that you use one of the other templates unless it’s absolutely necessary.

No predefined privileges. You can set any privileges except the following:

API key expiration

Because you can assign almost any privilege to Custom API keys, they’re at greater risk of exposure or loss.

To help mitigate this risk, you’ll be asked to set an expiration date when you configure a Custom API key. The default is 14 days, and keys expire at 23:59:59 UTC on the specified expiration date. You can choose an expiration date from among the following options:

  • 14 days

  • 1 month

  • 1 year

  • Never

Important

If you choose Never, manage your keys with extra care to ensure that those with sensitive privileges aren’t lost or exposed.

When an API key has an expiration date, its status will be updated to Soon to be expired 7 days before it expires. All organization administrators will receive email notifications at the following times:

  • 7 days before the key expires

  • 2 days before the key expires

  • Immediately after the key expires

Important

Expired API keys can’t be reactivated.

You can use the Create from existing feature to create a new key with settings carried over from an existing key.

Automatic API key deactivation

API keys may be deactivated automatically under the following circumstances:

  • When they haven’t been used for one year

  • When Coveo detects keys with sensitive privileges that are exposed or exhibit suspicious activity

Unused or inactive keys

Coveo will automatically deactivate unused or inactive API keys after one year based on the Last used date or, if the key was never used, the Activation date.

Note

The Last used date is updated every time an API key is used, regardless of whether the API call was allowed or denied.

This means that the Last used date will be updated under the following circumstances:

  • When an API call is denied because the key is deactivated

  • When an API call is denied because the key is expired

  • When an API call is denied because the IP address is restricted

The key’s status will be updated to Soon to be deactivated one month before the API key is deactivated. All organization administrators will receive email notifications at the following times:

  • 30 days before the key is deactivated

  • 15 days before the key is deactivated

  • 1 day before the key is deactivated

  • Immediately after the key is deactivated

Important

Custom API keys can’t be reactivated.

You can use the Create from existing feature to create a new key with settings carried over from an existing key.

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 never 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 perform 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 automatically deactivate exposed API keys with sensitive privileges or those exhibiting suspicious activity.

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 of between 2 and 30 days, based on the severity of the exposure or suspicious activity. Under rare circumstances, such as when PII is at risk of being leaked, Coveo may deactivate your key immediately.

Additional email notifications will be sent at the following times:

  • 3 days before the key is deactivated, if applicable

  • 24 hours before the key is deactivated

  • Immediately after the key is deactivated

Important

API keys that are automatically deactivated because they were exposed or exhibited suspicious activity can’t be reactivated.

You can use the Create from existing feature to create a new key with settings carried over from an existing key.

Leading practices

The following sections list the leading practices for managing API keys.

Creating API keys

Consider the following leading practices when creating API keys:

Tip

The API key templates should cover the majority of use cases, and they’re designed with these leading practices in mind. However, you should read through these practices if you plan to create a Custom key.

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

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

  • Don’t paste the API key value into the key’s name or description. The system won’t let you save a key when the value is in either the name or description.

  • Add IP address restrictions to API keys whenever possible.

  • Apply the principle of least privilege when assigning privileges to an API key.

  • If an API key has sensitive privileges, make sure that it isn’t publicly exposed, such as in the source code of your search interface.

  • If you plan to include an API key in the client-side code of a search interface, it should only be a key with one of the templates tagged as Can be public.

Editing API keys

Consider the following leading practice when editing API keys:

  • You must know where and how an API key is used before you edit its configuration. For example, adding IP restrictions could break processes that are using the key. It’s better to create a new API key and then deactivate the original one.

Using API keys

Consider the following leading practices when using API keys:

Sharing API keys

Consider the following leading practice when sharing API keys:

  • Only share API keys with legitimate stakeholders through secure channels.

Maintaining API keys

Consider the following leading practices when maintaining API keys:

  • You should regularly check with requesters to see if they still use the API keys that have been shared with them.

  • If you have API keys that are legitimately exposed in client-side code, you should deactivate and replace them regularly to prevent unauthorized usage. You can use the Create from existing feature to create a new key with settings carried over from an existing key.

  • Delete unused API keys. To check if an API key is still in use, refer to the API Keys (platform-ca | platform-eu | platform-au) page and review the Status column.

  • If you notice an API key that has more privileges than it needs, create a key that only includes the necessary privileges and deactivate the old one. You can use the Create from existing feature to create a new key with settings carried over from an existing one.

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

Create an API key

Before you create an API key in the Coveo Administration Console, review the leading practices.

Tip

Developers can also create API keys programmatically.

To create an API key

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

  2. In the Key purpose step, select a template which contains the privileges that best suit your use case, and then click Next.

    The next steps in the API key creation process change depending on the template you select in this step.

    The following sections describe the creation process for each template:

Create an Anonymous search key

  1. In the Identification step:

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

      Note

      The maximum length is 125 characters. If you exceed this limit, you’ll get an error when you click Add API key in the final step of the key creation process.

    2. (Optional) 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. Click Next.

  2. In the Configuration step:

    1. (Optional but strongly recommended) Select a search hub. Unless you’re using Coveo for Commerce, Coveo strongly recommends setting this to ensure that any query made using the API key enforces the selected search hub and is routed to the appropriate query pipeline.

      Important

      When you create an API key to authenticate requests for a Coveo for Commerce solution, you shouldn’t enforce a search hub in the key. For more information, see Coveo for Commerce API keys.

    2. Click Next.

  3. In the Access step:

    1. Select the groups in your Coveo organization that should be able to view or edit your API key. For more information, see Custom access level.

      Example

      You decide that members of Group A can edit the API key, while those in Group B can only view it.

  4. Click Add API key.

  5. In the API key successfully created dialog that appears:

    1. Click copy16px to copy the key to your clipboard.

      Important

      Copy the key immediately. This is the only time that it will be displayed.

    2. Click Done to close the dialog.

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

Create an Authenticated search key

  1. In the Identification step:

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

      Note

      The maximum length is 125 characters. If you exceed this limit, you’ll get an error when you click Add API key in the final step of the key creation process.

    2. (Optional) 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. Click Next.

  2. In the Configuration step:

    1. (Optional but strongly recommended) Select a search hub. Unless you’re using Coveo for Commerce, Coveo strongly recommends setting this to ensure that any query made using the API key enforces the selected search hub and is routed to the appropriate query pipeline.

      Important

      When you create an API key to authenticate requests for a Coveo for Commerce solution, you shouldn’t enforce a search hub in the key. For more information, see Coveo for Commerce API keys.

    2. (Optional) For increased security, you can enter IP addresses or ranges of addresses from which your API key can be used. Use Classless Inter-Domain Routing (CIDR) suffixes. However, private IPv4 addresses can’t be used for API keys.

      Example

      You want to allow the 256 IP addresses from 104.1.1.0 to 104.1.1.255. Under Allowed IPs, you enter: 104.1.1.0/24.

    3. Click Next.

  3. In the Access step:

    1. Select the groups in your Coveo organization that should be able to view or edit your API key. For more information, see Custom access level.

      Example

      You decide that members of Group A can edit the API key, while those in Group B can only view it.

  4. Click Add API key.

  5. In the API key successfully created dialog that appears:

    1. Click copy16px to copy the key to your clipboard.

      Important

      Copy the key immediately. This is the only time that it will be displayed.

    2. Click Done to close the dialog.

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

Create a Usage analytics key

  1. In the Identification step:

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

      Note

      The maximum length is 125 characters. If you exceed this limit, you’ll get an error when you click Add API key in the final step of the key creation process.

    2. (Optional) 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. Click Next.

  2. In the Access step:

    1. Select the groups in your Coveo organization that should be able to view or edit your API key. For more information, see Custom access level.

      Example

      You decide that members of Group A can edit the API key, while those in Group B can only view it.

  3. Click Add API key.

  4. In the API key successfully created dialog that appears:

    1. Click copy16px to copy the key to your clipboard.

      Important

      Copy the key immediately. This is the only time that it will be displayed.

    2. Click Done to close the dialog.

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

Create a Search page key

  1. In the Identification step:

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

      Note

      The maximum length is 125 characters. If you exceed this limit, you’ll get an error when you click Add API key in the final step of the key creation process.

    2. (Optional) 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. Click Next.

  2. In the Configuration step:

    1. (Optional but strongly recommended) Select a search hub. Unless you’re using Coveo for Commerce, Coveo strongly recommends setting this to ensure that any query made using the API key enforces the selected search hub and is routed to the appropriate query pipeline.

      Important

      When you create an API key to authenticate requests for a Coveo for Commerce solution, you shouldn’t enforce a search hub in the key. For more information, see Coveo for Commerce API keys.

    2. Click Next.

  3. In the Access step:

    1. Select the groups in your Coveo organization that should be able to view or edit your API key. For more information, see Custom access level.

      Example

      You decide that members of Group A can edit the API key, while those in Group B can only view it.

  4. Click Add API key.

  5. In the API key successfully created dialog that appears:

    1. Click copy16px to copy the key to your clipboard.

      Important

      Copy the key immediately. This is the only time that it will be displayed.

    2. Click Done to close the dialog.

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

Create a Custom key

  1. In the Identification step:

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

      Note

      The maximum length is 125 characters. If you exceed this limit, you’ll get an error when you click Add API key in the final step of the key creation process.

    2. (Optional) 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. Click Next.

  2. In the Privileges step, you can choose whichever privileges you want to grant to your API key, and then click Next.

    Important

    To prevent misuse, you can’t grant the following privileges to a custom API key:

    If you need these privileges, you can grant them using other templates.

  3. In the Configuration step:

    1. Set an expiration date for your API key.

    2. (Optional) For increased security, you can enter IP addresses or ranges of addresses from which your API key can be used. Use Classless Inter-Domain Routing (CIDR) suffixes. However, private IPv4 addresses can’t be used for API keys.

      Example

      You want to allow the 256 IP addresses from 104.1.1.0 to 104.1.1.255. Under Allowed IPs, you enter: 104.1.1.0/24.

    3. Click Next.

  4. In the Access step:

    1. Select the groups in your Coveo organization that should be able to view or edit your API key. For more information, see Custom access level.

      Example

      You decide that members of Group A can edit the API key, while those in Group B can only view it.

    2. Click Next.

  5. In the Review step, you can check your configuration before you finalize your API key.

    Clicking Edit in any section will return you to that step in the API key creation process.

  6. Click Add API key.

  7. In the API key successfully created dialog that appears:

    1. Click copy16px to copy the key to your clipboard.

      Important

      Copy the key immediately. This is the only time that it will be displayed.

    2. Click Done to close the dialog.

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

Create an API key from an existing key

You can create a new API key with the same settings as an existing key. This includes keys that have been deactivated for any reason.

To create an API key from an existing key

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

  2. In the Action bar, click Create from existing.

    Tip

    You can also use this feature while editing a key. Click Manage API key and select Create from existing from the dropdown menu.

    The API key creator will open, although the Key purpose step will be skipped and the new key will automatically use the same template as the existing one.

  3. Proceed with the standard API key creation process from the Identification step, depending on the template of the existing key:

Edit an API key

You can’t edit the privileges or expiration date assigned to an API key.

If you need to change either the privileges or expiration date, you’ll have to create a new key and deactivate the old one.

To edit an API key

  1. On the API Keys (platform-ca | platform-eu | platform-au) page, select the API key that you want to edit.

  2. In the Action bar, click Edit.

  3. In the Overview tab, you can edit the key’s name, description, and list of allowed IPs.

  4. In the Access tab, you can edit the access restrictions.

  5. Click Save.

Deactivate an API key

When you deactivate an API key, it can no longer be used to make calls to the Coveo Platform, but its configuration is kept intact. You can still use it with the Create from existing feature if you need a similar key.

To deactivate an API key

  1. On the API Keys (platform-ca | platform-eu | platform-au) page, select the API key that you want to deactivate.

  2. In the Action bar, click More > Deactivate.

    Important

    Custom API keys can’t be reactivated.

    When you try to deactivate a Custom key, an additional dialog will appear. Check the I understand box, and then click Deactivate to confirm.

When you deactivate an API key, expect a delay of a few minutes before it stops working.

Activate an API key

You can activate some API keys that have been deactivated. You can’t reactivate API keys that were created using the Custom template, keys that have expired, or keys that were automatically deactivated because they were exposed.

To activate an API key

  1. On the API Keys (platform-ca | platform-eu | platform-au) page, select the API key that you want to activate.

  2. In the Action bar, click More > Activate.

    Important

    If you try to activate a Custom key, the Activate option will be grayed out.

Delete an API key

Deleting unused API keys is a good practice.

Important

Deleting an API key that’s currently in use will break any applications that use it to get services from your Coveo organization. You should confirm with the API key stakeholders that the key is no longer in use before you delete it.

To delete an API key

  1. On the API Keys (platform-ca | platform-eu | platform-au) page, select the API key that you want to delete.

  2. In the Action bar, click Delete.

    Tip

    If the API key has already expired or been deactivated, you can click Delete in the Status column.

  3. In the dialog that opens, click Delete to confirm.

When you delete an API key, expect a delay of a few minutes before it stops working.

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.

Coveo for Commerce API keys

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

When you create an API key to authenticate 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 that you use 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.

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.