--- title: Manage API keys slug: '1718' canonical_url: https://docs.coveo.com/en/1718/ collection: manage-an-organization source_format: adoc --- # Manage API keys Developers working on a Coveo-powered deployment may require _API keys_ to interact programmatically with the [Coveo Platform](https://docs.coveo.com/en/186/). An API key is an access token that carries a certain set of [privileges](https://docs.coveo.com/en/228/) in a specific [Coveo organization](https://docs.coveo.com/en/185/). Anyone with an authorized IP address can use an API key to [authenticate](https://docs.coveo.com/en/2120/) REST API calls for which this key grants the required [privileges](https://docs.coveo.com/en/228/). The following are typical situations in which an API key is required: * A developer is working on a [search interface](https://docs.coveo.com/en/2741/) that can show both public and secured content. They need an API key to implement [search token authentication](https://docs.coveo.com/en/56/). * A developer is building a [custom connector](https://docs.coveo.com/en/1702#custom-built-connectors) that uses the [Push API](https://docs.coveo.com/en/68/) to [index](https://docs.coveo.com/en/204/) content behind a firewall. They need an API key to [authenticate](https://docs.coveo.com/en/2120/) Push API calls. This article explains how to [create](#create-an-api-key) and manage API keys. It includes information about API key [templates](#api-key-templates), [expiration](#api-key-expiration), and [automatic deactivation](#automatic-api-key-deactivation). It also provides a list of [leading practices](#leading-practices). ## API key templates The [Coveo Administration Console](https://docs.coveo.com/en/183/) uses templates to grant privileges to API keys. Most of these templates are predefined bundles of [privileges](https://docs.coveo.com/en/228/) that are suitable for common use cases. The **Custom** template doesn't have any predefined [privileges](https://docs.coveo.com/en/228/), so you can set [whichever ones you need](https://docs.coveo.com/en/1707/), with some limitations. This flexibility comes with added risks, so you should consult the [leading practices](#creating-api-keys) 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](https://docs.coveo.com/en/228/) that could be exploited by malicious users. [%header,cols="1,1,2,2a"] |=== |Template |Privacy |Description |Privileges |**Anonymous search** |Can be public |To query for public content and send [data](https://docs.coveo.com/en/259/) on a [search interface](https://docs.coveo.com/en/2741/) that doesn't require any form of [authentication](https://docs.coveo.com/en/2120/). Can be embedded directly in the [search interface](https://docs.coveo.com/en/2741/). |* [Execute queries](https://docs.coveo.com/en/1707#execute-queries-domain): Allowed * [Execute agent queries](https://docs.coveo.com/en/1707#execute-agent-queries-domain): Allowed * [Analytics data](https://docs.coveo.com/en/1707#analytics-data-domain): Push |**Authenticated search** |Must remain private |To support [authenticated](https://docs.coveo.com/en/2120/) [queries](https://docs.coveo.com/en/231/) and send [data](https://docs.coveo.com/en/259/). This key must be stored on a secured backend and used to generate [search tokens](https://docs.coveo.com/en/1346/) based on the [security identity](https://docs.coveo.com/en/240/) of the logged-in user. |* [Search - Impersonate](https://docs.coveo.com/en/1707#impersonate-domain-search): Allowed * [Analytics data](https://docs.coveo.com/en/1707#analytics-data-domain): Push |**Usage analytics** |Can be public |Use this key to send [data](https://docs.coveo.com/en/259/) to your [Coveo organization](https://docs.coveo.com/en/185/) using any [security identity](https://docs.coveo.com/en/240/). |* [Analytics - Impersonate](https://docs.coveo.com/en/1707#impersonate-domain-analytics): Allowed * [Analytics data](https://docs.coveo.com/en/1707#analytics-data-domain): Push |**Search pages** |Can be public |Use this key when implementing Coveo-hosted search pages. |* [Execute queries](https://docs.coveo.com/en/1707#execute-queries-domain): Allowed * [Execute agent queries](https://docs.coveo.com/en/1707#execute-agent-queries-domain): Allowed * [Analytics data](https://docs.coveo.com/en/1707#analytics-data-domain): Push * [Search pages and IPX](https://docs.coveo.com/en/1707#search-pages-and-ipx-domain): View |**Anonymous Case Assist** |Can be public |To allow customers to use Case Assist anonymously and send usage analytics data. The users don’t have to log in to use Case Assist. |* [Analytics data](https://docs.coveo.com/en/1707#analytics-data-domain): Push * [Use Case Assist](https://docs.coveo.com/en/1707#use-case-assist-domain): Allowed |**Push API** |Must remain private |To authenticate Push API calls when pushing items and their permissions into a source, and security identities into a security identity provider. The users don’t have to log in to use Case Assist. |* [Push items to sources](https://docs.coveo.com/en/1707#push-items-to-sources-domain): Allowed * [Sources](https://docs.coveo.com/en/1707#sources-domain): View all * [Push identities to security providers](https://docs.coveo.com/en/1707#push-identities-to-security-providers-domain): Allowed * [Security identity providers](https://docs.coveo.com/en/1707#security-identity-providers-domain): View * [Organization](https://docs.coveo.com/en/1707#organization-domain): View |**Crawling Module administration** |Must remain private |When installing the Crawling Module, you’re asked to log in to Coveo and choose an organization to pair with your Crawling Module. If your environment doesn't allow you to log in to Coveo, use this template to generate a key, and then provide this key to the installer. This alternative allows the installer to authenticate with your Coveo organization and complete the installation. Your key is only used for the initial handshake with Coveo. After that, the Crawling Module creates its own API key automatically. |* [Crawling Module](https://docs.coveo.com/en/1707#crawling-module-domain): Edit * [Crawling Module log request](https://docs.coveo.com/en/1707#crawling-module-log-request-domain): Edit * [Push identities to security providers](https://docs.coveo.com/en/1707#push-identities-to-security-providers-domain): Allowed * [Push items to sources](https://docs.coveo.com/en/1707#push-items-to-sources-domain): Allowed * [Security identity providers](https://docs.coveo.com/en/1707#security-identity-providers-domain): View * [Sources](https://docs.coveo.com/en/1707#sources-domain): View all * [API keys](https://docs.coveo.com/en/1707#api-keys-domain): Create * [On-premises administration](https://docs.coveo.com/en/1707#on-premises-administration-domain): Edit * [Organization](https://docs.coveo.com/en/1707#organization-domain): View |**View all content** |Must remain private |Use this key to validate the extracted metadata and ensure that secured content is properly indexed. This is a very powerful key that bypasses item access permissions. It should only be used for troubleshooting purposes or when a comprehensive overview of all indexed content is required. |* [Search - View all content](https://docs.coveo.com/en/1707#view-all-content-domain): Allowed * [Execute queries](https://docs.coveo.com/en/1707#execute-queries-domain): Allowed |**Custom** |Must remain private |Create a custom combination of [privileges](https://docs.coveo.com/en/228/). Before using this template, check that no other template meets your needs. |No predefined [privileges](https://docs.coveo.com/en/228/). You can set any [privileges](https://docs.coveo.com/en/228/) **except the following**: * [Execute queries](https://docs.coveo.com/en/1707#execute-queries-domain): Allowed * [Search - Impersonate](https://docs.coveo.com/en/1707#impersonate-domain-search): Allowed * [Analytics data](https://docs.coveo.com/en/1707#analytics-data-domain): Push |=== ## API key expiration When configuring a key from a template such as **View all content** and **Custom**, you'll be asked to set an expiration date for your key. This is because your key carries or may carry powerful [privileges](https://docs.coveo.com/en/228/) that could be misused if the key is exposed or lost. The expiration date is a safeguard to ensure that the key doesn't remain valid indefinitely. For example, a **View all content** key is used to view all indexed content, including sensitive content that shouldn't be publicly accessible. Since it's intended for troubleshooting purposes, it will expire after a short period. As a result, if it's lost or exposed, it won't remain valid for long, reducing the risk of misuse. On the other hand, with a **Custom** key, you can set the expiration date to `Never` if you need it to remain valid indefinitely. > **Important** > > If you choose `Never`, manage your keys with extra care to ensure that those with sensitive privileges aren't lost or exposed. Keys expire at 23:59:59 UTC on the specified expiration date. When an API key has an expiration date, its status is updated to `Soon to be expired` 7 days before it expires. All [organization](https://docs.coveo.com/en/185/) 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** > > 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**](#create-an-api-key-from-an-existing-key) feature to [rotate](https://docs.coveo.com/en/p7sb0148/) your API keys. ## 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](https://docs.coveo.com/en/228/) 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 One month before an API key is deactivated, its status will be updated to `Soon to be deactivated`. The **Status** column will show you the last date that the key was used and the date at which it will be deactivated. You'll also have the option to manually [delete it](#delete-an-api-key) or [keep it active for one year](#keep-a-key-active-for-one-year). ![API key with Soon to be deactivated status | Coveo Platform](https://docs.coveo.com/en/assets/images/manage-an-organization/api-key-soon-to-be-deactivated.png) All [organization](https://docs.coveo.com/en/185/) 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** > > 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**](#create-an-api-key-from-an-existing-key) feature to [rotate](https://docs.coveo.com/en/p7sb0148/) your API keys. ### Keep a key active for one year When an API key has the `Soon to be deactivated` status, you can manually reset its activation date to prevent it from being deactivated. In the **Status** column, click **Keep active for a year**. This will reset the key's activation date to the current date. ### Exposed keys Exposed API keys with sensitive [privileges](https://docs.coveo.com/en/228/) may pose a significant risk to the security of your [Coveo organization](https://docs.coveo.com/en/185/). Unauthorized third parties can use them to perform harmful actions or access restricted content. This can include [indexed](https://docs.coveo.com/en/204/) content or [data](https://docs.coveo.com/en/259/) that contains personally identifiable information (PII). > **Important** > > For now, although this section provides information about automatically deactivating exposed API keys, Coveo isn't setting a deactivation date for keys that are flagged as `Exposed`. > > In the future, most `Exposed` keys will have a specific deactivation date. To protect your [organization](https://docs.coveo.com/en/185/), when Coveo detects an exposed API key with sensitive [privileges](https://docs.coveo.com/en/228/), or one that's exhibiting suspicious activity, it automatically updates the key's status to `Exposed`. The **Status** column will show you the date at which the key will be deactivated. Click **See details** to jump to the **Overview** tab, where you can see why the key was flagged as `Exposed`. ![Exposed API key warning in Overview tab | Coveo Platform](https://docs.coveo.com/en/assets/images/manage-an-organization/exposed-api-key-warning-in-overview-tab.png) An `Exposed` API key will typically 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. Alternatively, Coveo may not set a specific deactivation date. In this case, the `Exposed` status serves as a warning, and you should immediately [rotate](https://docs.coveo.com/en/p7sb0148/) it yourself by [creating a new key from the existing key](#create-an-api-key-from-an-existing-key). > **Note** > > The **Create from existing** feature doesn't deactivate or set an expiration date for the original key. > If you use it to [rotate](https://docs.coveo.com/en/p7sb0148/) an API key, you'll have to [deactivate](#deactivate-an-api-key) the original key yourself. When an API key is flagged as `Exposed`, all [organization](https://docs.coveo.com/en/185/) administrators and the account security contact will receive an email notification explaining the reason. Additional email notifications will be sent at the following times, if applicable: * 3 days before the key is deactivated * 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**](#create-an-api-key-from-an-existing-key) feature to [rotate](https://docs.coveo.com/en/p7sb0148/) your API keys. ## 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](#create-an-api-key): > **Tip** > > The API key [templates](#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](#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](#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. * Add IP address restrictions to API keys whenever possible. * Apply the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when assigning [privileges](https://docs.coveo.com/en/228/) to an API key. * If an API key has sensitive [privileges](https://docs.coveo.com/en/228/), make sure that it isn't publicly exposed, such as in the source code of your [search interface](https://docs.coveo.com/en/2741/). * If you plan to [include an API key in the client-side code of a search interface](https://docs.coveo.com/en/105/), it should only be a key with one of the [templates](#api-key-templates) tagged as **Can be public**. ### Editing API keys Consider the following leading practice when [editing API keys](#edit-an-api-key): * 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](#create-an-api-key) and then [deactivate the original one](#deactivate-an-api-key). ### Using API keys Consider the following leading practices when using API keys: * Only use an API key in a server-side software process where a limited number of authorized people can see it. This is particularly important when the API key carries sensitive [privileges](https://docs.coveo.com/en/228/) that malicious users could exploit. For example, the `Allowed` [access level](https://docs.coveo.com/en/2818/) on the [Search - Impersonate](https://docs.coveo.com/en/1707#impersonate-domain-search) domain could let someone [impersonate](https://docs.coveo.com/en/2737/) any other user and access content that they shouldn't normally be able to access. > **Important** > > Coveo may [deactivate exposed API keys](#exposed-keys) with sensitive [privileges](https://docs.coveo.com/en/228/) or those showing suspicious activity. * If your [search interface](https://docs.coveo.com/en/2741/) includes [content to which user access is based on the repository's permission system](https://docs.coveo.com/en/1779#same-users-and-groups-as-in-your-content-system), generate a [search token](https://docs.coveo.com/en/1346/) for each user instead of using an API key. The [search interface](https://docs.coveo.com/en/2741/) developer must set up a server-side mechanism to [generate the search tokens using an API key](https://docs.coveo.com/en/56/). ### 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](#deactivate-an-api-key) and replace them regularly to prevent unauthorized usage. You can use the [**Create from existing**](#create-an-api-key-from-an-existing-key) feature to create a new key with settings carried over from an existing key. * [Delete](#delete-an-api-key) unused API keys. To check if an API key is still in use, refer to the [**API Keys**](https://platform.cloud.coveo.com/admin/#/orgid/organization/api-access/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/organization/api-access/)) page and review the **Status** column. * If you notice an API key that has more [privileges](https://docs.coveo.com/en/228/) than it needs, [create a key](#create-an-api-key) that only includes the necessary privileges and [deactivate](#deactivate-an-api-key) the old one. You can use the [**Create from existing**](#create-an-api-key-from-an-existing-key) 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](#delete-an-api-key) the API keys that they used. ## Create an API key Before you create an API key in the [Coveo Administration Console](https://docs.coveo.com/en/183/), review the [leading practices](#leading-practices). > **Tip** > > Developers can also [create API keys programmatically](https://docs.coveo.com/en/82#create-an-api-key-programmatically). To create an API key . On the [**API Keys**](https://platform.cloud.coveo.com/admin/#/orgid/organization/api-access/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/organization/api-access/)) page, click **Add key**. . In the **Key purpose** step, select a [template](#api-key-templates) 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: ** [Anonymous search](#create-an-anonymous-search-key) ** [Authenticated search](#create-an-authenticated-search-key) ** [Usage analytics](#create-a-usage-analytics-key) ** [Search page](#create-a-search-page-key) ** [Anonymous Case Assist](#create-an-anonymous-case-assist-key) ** [Push API](#create-a-push-api-key) ** [Crawling Module administration](#create-a-crawling-module-administration-key) ** [View all content](#create-a-view-all-content-key) ** [Custom](#create-a-custom-key) ### Create an Anonymous search key . In the **Identification** step: .. In the **Name** box, enter a name for your API key. A good name should let you easily identify the purpose of the key. .. (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. .. Click **Next**. . In the **Configuration** step: .. Select the [sources](https://docs.coveo.com/en/246/) where the API key can push content. .. Select the [security identity providers](https://docs.coveo.com/en/242/) where the API key can push data. .. (Optional but strongly recommended) Select a [search hub](https://docs.coveo.com/en/1342/). Unless you're using Coveo for Commerce, Coveo strongly recommends setting this to ensure that any [query](https://docs.coveo.com/en/231/) made using the API key enforces the selected [search hub](https://docs.coveo.com/en/1342/) and is routed to the appropriate [query pipeline](https://docs.coveo.com/en/180/). > **Important** > > When you create an API key to [authenticate](https://docs.coveo.com/en/2120/) requests for a Coveo for Commerce solution, you shouldn't enforce a [search hub](https://docs.coveo.com/en/1342/) in the key. > For more information, see [Coveo for Commerce API keys](#coveo-for-commerce-api-keys). . In the **Access** step, select the [groups](https://docs.coveo.com/en/2867/) in your [Coveo organization](https://docs.coveo.com/en/185/) that should be able to view or edit your API key. For more information, see [Custom access level](https://docs.coveo.com/en/3151#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. . Click **Add API key**. . In the **API key successfully created** dialog that appears: .. Click icon:clipboard-text[alt=clipboard-text,width=16] to copy the key to your clipboard. > **Important** > > Copy the key immediately. > This is the only time that it will be displayed. .. Click **Done** to close the dialog. . 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 . In the **Identification** step: .. In the **Name** box, enter a name for your API key. A good name should let you easily identify the purpose of the key. .. (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. .. Click **Next**. . In the **Configuration** step: .. Select the [sources](https://docs.coveo.com/en/246/) where the API key can push content. .. Select the [security identity providers](https://docs.coveo.com/en/242/) where the API key can push data. .. (Optional but strongly recommended) Select a [search hub](https://docs.coveo.com/en/1342/). Unless you're using Coveo for Commerce, Coveo strongly recommends setting this to ensure that any [query](https://docs.coveo.com/en/231/) made using the API key enforces the selected [search hub](https://docs.coveo.com/en/1342/) and is routed to the appropriate [query pipeline](https://docs.coveo.com/en/180/). > **Important** > > When you create an API key to [authenticate](https://docs.coveo.com/en/2120/) requests for a Coveo for Commerce solution, you shouldn't enforce a [search hub](https://docs.coveo.com/en/1342/) in the key. > For more information, see [Coveo for Commerce API keys](#coveo-for-commerce-api-keys). .. (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)](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) suffixes. However, [private IPv4 addresses](https://en.wikipedia.org/wiki/Private_network#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`. . In the **Access** step, select the [groups](https://docs.coveo.com/en/2867/) in your [Coveo organization](https://docs.coveo.com/en/185/) that should be able to view or edit your API key. For more information, see [Custom access level](https://docs.coveo.com/en/3151#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. . Click **Add API key**. . In the **API key successfully created** dialog that appears: .. Click icon:clipboard-text[alt=clipboard-text,width=16] to copy the key to your clipboard. > **Important** > > Copy the key immediately. > This is the only time that it will be displayed. .. Click **Done** to close the dialog. . 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 . In the **Identification** step: .. In the **Name** box, enter a name for your API key. A good name should let you easily identify the purpose of the key. .. (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. .. Click **Next**. . In the **Access** step, select the [groups](https://docs.coveo.com/en/2867/) in your [Coveo organization](https://docs.coveo.com/en/185/) that should be able to view or edit your API key. For more information, see [Custom access level](https://docs.coveo.com/en/3151#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. . Click **Add API key**. . In the **API key successfully created** dialog that appears: .. Click icon:clipboard-text[alt=clipboard-text,width=16] to copy the key to your clipboard. > **Important** > > Copy the key immediately. > This is the only time that it will be displayed. .. Click **Done** to close the dialog. . 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 . In the **Identification** step: .. In the **Name** box, enter a name for your API key. A good name should let you easily identify the purpose of the key. .. (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. .. Click **Next**. . In the **Configuration** step: .. Select the [sources](https://docs.coveo.com/en/246/) where the API key can push content. .. Select the [security identity providers](https://docs.coveo.com/en/242/) where the API key can push data. .. (Optional but strongly recommended) Select a [search hub](https://docs.coveo.com/en/1342/). Unless you're using Coveo for Commerce, Coveo strongly recommends setting this to ensure that any [query](https://docs.coveo.com/en/231/) made using the API key enforces the selected [search hub](https://docs.coveo.com/en/1342/) and is routed to the appropriate [query pipeline](https://docs.coveo.com/en/180/). > **Important** > > When you create an API key to [authenticate](https://docs.coveo.com/en/2120/) requests for a Coveo for Commerce solution, you shouldn't enforce a [search hub](https://docs.coveo.com/en/1342/) in the key. > For more information, see [Coveo for Commerce API keys](#coveo-for-commerce-api-keys). . In the **Access** step, select the [groups](https://docs.coveo.com/en/2867/) in your [Coveo organization](https://docs.coveo.com/en/185/) that should be able to view or edit your API key. For more information, see [Custom access level](https://docs.coveo.com/en/3151#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. . Click **Add API key**. . In the **API key successfully created** dialog that appears: .. Click icon:clipboard-text[alt=clipboard-text,width=16] to copy the key to your clipboard. > **Important** > > Copy the key immediately. > This is the only time that it will be displayed. .. Click **Done** to close the dialog. . 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 Anonymous Case Assist key . In the **Identification** step: .. In the **Name** box, enter a name for your API key. A good name should let you easily identify the purpose of the key. .. (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. .. Click **Next**. . In the **Access** step, select the [groups](https://docs.coveo.com/en/2867/) in your [Coveo organization](https://docs.coveo.com/en/185/) that should be able to view or edit your API key. For more information, see [Custom access level](https://docs.coveo.com/en/3151#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. . Click **Add API key**. . In the **API key successfully created** dialog that appears: .. Click icon:clipboard-text[alt=clipboard-text,width=16] to copy the key to your clipboard. > **Important** > > Copy the key immediately. > This is the only time that it will be displayed. .. Click **Done** to close the dialog. . 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 Push API key . In the **Identification** step: .. In the **Name** box, enter a name for your API key. A good name should let you easily identify the purpose of the key. .. (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. .. Click **Next**. . In the **Configuration** step: .. Select the [sources](https://docs.coveo.com/en/246/) where the API key can push content. .. Select the [security identity providers](https://docs.coveo.com/en/242/) where the API key can push data. .. (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)](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) suffixes. However, [private IPv4 addresses](https://en.wikipedia.org/wiki/Private_network#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`. . In the **Access** step, select the [groups](https://docs.coveo.com/en/2867/) in your [Coveo organization](https://docs.coveo.com/en/185/) that should be able to view or edit your API key. For more information, see [Custom access level](https://docs.coveo.com/en/3151#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. ### Create a Crawling Module administration key . In the **Identification** step: .. In the **Name** box, enter a name for your API key. A good name should let you easily identify the purpose of the key. .. (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. .. Click **Next**. . In the **Configuration** step: .. Select the [sources](https://docs.coveo.com/en/246/) where the API key can push content. .. Select the [security identity providers](https://docs.coveo.com/en/242/) where the API key can push data. .. (Optional but strongly recommended) Select a [search hub](https://docs.coveo.com/en/1342/). Unless you're using Coveo for Commerce, Coveo strongly recommends setting this to ensure that any [query](https://docs.coveo.com/en/231/) made using the API key enforces the selected [search hub](https://docs.coveo.com/en/1342/) and is routed to the appropriate [query pipeline](https://docs.coveo.com/en/180/). > **Important** > > When you create an API key to [authenticate](https://docs.coveo.com/en/2120/) requests for a Coveo for Commerce solution, you shouldn't enforce a [search hub](https://docs.coveo.com/en/1342/) in the key. > For more information, see [Coveo for Commerce API keys](#coveo-for-commerce-api-keys). .. Set an [expiration date](#api-key-expiration) for your API key. > **Important** > > The **View all content** API key template is very powerful. > You must set an expiration date of 1-14 days when you create a key using this template. .. (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)](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) suffixes. However, [private IPv4 addresses](https://en.wikipedia.org/wiki/Private_network#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`. . In the **Access** step, select the [groups](https://docs.coveo.com/en/2867/) in your [Coveo organization](https://docs.coveo.com/en/185/) that should be able to view or edit your API key. For more information, see [Custom access level](https://docs.coveo.com/en/3151#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. . Click **Add API key**. . In the **API key successfully created** dialog that appears: .. Click icon:clipboard-text[alt=clipboard-text,width=16] to copy the key to your clipboard. > **Important** > > Copy the key immediately. > This is the only time that it will be displayed. .. Click **Done** to close the dialog. . 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 View all content key . In the **Identification** step: .. In the **Name** box, enter a name for your API key. A good name should let you easily identify the purpose of the key. .. (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. .. Click **Next**. . In the **Configuration** step: .. Select the [sources](https://docs.coveo.com/en/246/) where the API key can push content. .. Select the [security identity providers](https://docs.coveo.com/en/242/) where the API key can push data. .. (Optional but strongly recommended) Select a [search hub](https://docs.coveo.com/en/1342/). Unless you're using Coveo for Commerce, Coveo strongly recommends setting this to ensure that any [query](https://docs.coveo.com/en/231/) made using the API key enforces the selected [search hub](https://docs.coveo.com/en/1342/) and is routed to the appropriate [query pipeline](https://docs.coveo.com/en/180/). > **Important** > > When you create an API key to [authenticate](https://docs.coveo.com/en/2120/) requests for a Coveo for Commerce solution, you shouldn't enforce a [search hub](https://docs.coveo.com/en/1342/) in the key. > For more information, see [Coveo for Commerce API keys](#coveo-for-commerce-api-keys). .. Set an [expiration date](#api-key-expiration) for your API key. > **Important** > > The **View all content** API key template is very powerful. > You must set an expiration date of 1-14 days when you create a key using this template. .. (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)](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) suffixes. However, [private IPv4 addresses](https://en.wikipedia.org/wiki/Private_network#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`. . In the **Access** step, select the [groups](https://docs.coveo.com/en/2867/) in your [Coveo organization](https://docs.coveo.com/en/185/) that should be able to view or edit your API key. For more information, see [Custom access level](https://docs.coveo.com/en/3151#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. . Click **Add API key**. . In the **API key successfully created** dialog that appears: .. Click icon:clipboard-text[alt=clipboard-text,width=16] to copy the key to your clipboard. > **Important** > > Copy the key immediately. > This is the only time that it will be displayed. .. Click **Done** to close the dialog. . 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 . In the **Identification** step: .. In the **Name** box, enter a name for your API key. A good name should let you easily identify the purpose of the key. .. (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. .. Click **Next**. . 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 any of the following [privileges](https://docs.coveo.com/en/228/) to a custom API key: > > * Search service > > ** [Execute queries](https://docs.coveo.com/en/1707#execute-queries-domain): Allowed > > ** [Impersonate](https://docs.coveo.com/en/1707#impersonate-domain-search): Allowed > > * Analytics service > > ** [Analytics data](https://docs.coveo.com/en/1707#analytics-data-domain): Push > > ** [Impersonate](https://docs.coveo.com/en/1707#impersonate-domain-Analytics): Allowed > > If you need these privileges, you can grant them using other [templates](https://docs.coveo.com/en/1718#api-key-templates). . In the **Configuration** step: .. Select the [sources](https://docs.coveo.com/en/246/) where the API key can push content. .. Select the [security identity providers](https://docs.coveo.com/en/242/) where the API key can push data. .. (Optional but strongly recommended) Select a [search hub](https://docs.coveo.com/en/1342/). Unless you're using Coveo for Commerce, Coveo strongly recommends setting this to ensure that any [query](https://docs.coveo.com/en/231/) made using the API key enforces the selected [search hub](https://docs.coveo.com/en/1342/) and is routed to the appropriate [query pipeline](https://docs.coveo.com/en/180/). > **Important** > > When you create an API key to [authenticate](https://docs.coveo.com/en/2120/) requests for a Coveo for Commerce solution, you shouldn't enforce a [search hub](https://docs.coveo.com/en/1342/) in the key. > For more information, see [Coveo for Commerce API keys](#coveo-for-commerce-api-keys). .. Set an [expiration date](#api-key-expiration) for your API key. .. (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)](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) suffixes. However, [private IPv4 addresses](https://en.wikipedia.org/wiki/Private_network#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`. . In the **Access** step, select the [groups](https://docs.coveo.com/en/2867/) in your [Coveo organization](https://docs.coveo.com/en/185/) that should be able to view or edit your API key. For more information, see [Custom access level](https://docs.coveo.com/en/3151#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. .. Click **Next**. . 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. . Click **Add API key**. . In the **API key successfully created** dialog that appears: .. Click icon:clipboard-text[alt=clipboard-text,width=16] to copy the key to your clipboard. > **Important** > > Copy the key immediately. > This is the only time that it will be displayed. .. Click **Done** to close the dialog. . 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. > **Note** > > The **Create from existing** feature doesn't deactivate or set an expiration date for the original key. > If you use it to [rotate](https://docs.coveo.com/en/p7sb0148/) an API key, you'll have to [deactivate](#deactivate-an-api-key) the original key yourself. To create an API key from an existing key . On the [**API Keys**](https://platform.cloud.coveo.com/admin/#/orgid/organization/api-access/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/organization/api-access/)) page, select an API key. . 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](#api-key-templates) as the existing one. . Proceed with the standard API key creation process from the **Identification** step, depending on the template of the existing key: ** [Anonymous search](#create-an-anonymous-search-key) ** [Authenticated search](#create-an-authenticated-search-key) ** [Usage analytics](#create-a-usage-analytics-key) ** [Search page](#create-a-search-page-key) ** [Anonymous Case Assist](#create-an-anonymous-case-assist-key) ** [Push API](#create-a-push-api-key) ** [View all content](#create-a-view-all-content-key) ** [Custom](#create-a-custom-key) ## Edit an API key You can't edit the [privileges](https://docs.coveo.com/en/228/) or [expiration date](#api-key-expiration) assigned to an API key. Instead, you must [create a new key](#create-an-api-key) and [deactivate the old one](#deactivate-an-api-key). To edit an API key . On the [**API Keys**](https://platform.cloud.coveo.com/admin/#/orgid/organization/api-access/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/organization/api-access/)) page, select the API key that you want to edit. . In the Action bar, click **Edit**. . On the **Overview** tab, you can edit the key's name, description, and list of allowed IPs. . On the **Access** tab, you can edit the access restrictions. . 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](https://docs.coveo.com/en/186/), but its configuration is kept intact. You can still use it with the [**Create from existing**](#create-an-api-key-from-an-existing-key) feature if you need a similar key. To deactivate an API key . On the [**API Keys**](https://platform.cloud.coveo.com/admin/#/orgid/organization/api-access/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/organization/api-access/)) page, select the API key that you want to deactivate. . In the Action bar, click **More** > **Deactivate**. > **Important** > > **Custom** API keys can't be [reactivated](#activate-an-api-key). > > 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](#deactivate-an-api-key). You can't reactivate API keys that were created using the **Custom** [template](#api-key-templates), keys that have [expired](#api-key-expiration), or keys that were automatically deactivated because they were [exposed](#exposed-keys). To activate an API key . On the [**API Keys**](https://platform.cloud.coveo.com/admin/#/orgid/organization/api-access/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/organization/api-access/)) page, select the API key that you want to activate. . 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](#leading-practices). > **Important** > > Deleting an API key that's currently in use will break any applications that use it to get services from your [Coveo organization](https://docs.coveo.com/en/185/). > 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 . On the [**API Keys**](https://platform.cloud.coveo.com/admin/#/orgid/organization/api-access/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/organization/api-access/)) page, select the API key that you want to delete. . In the Action bar, click **Delete**. > **Tip** > > If the API key has already [expired](#api-key-expiration) or been [deactivated](#deactivate-an-api-key), you can click **Delete** in the **Status** column. . 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](https://docs.coveo.com/en/173/) related to API keys for investigation or troubleshooting purposes. To do so, in the upper-right corner of the [**API Keys**](https://platform.cloud.coveo.com/admin/#/orgid/organization/api-access/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/organization/api-access/)) page, click [clock]. ## Coveo for Commerce API keys In Coveo for Commerce scenarios, [queries](https://docs.coveo.com/en/231/) target the [Commerce API](https://docs.coveo.com/en/103/), which automatically enforces [search hub](https://docs.coveo.com/en/1342/) values based on the [commerce interface](https://docs.coveo.com/en/o4ue6279/) from which the [query](https://docs.coveo.com/en/231/) originates. When you create an API key to [authenticate](https://docs.coveo.com/en/2120/) requests from a Coveo-powered Commerce interface, ensure that the API key doesn't specify the [search hub](https://docs.coveo.com/en/1342/), as it's automatically set by the Commerce API. If your [index](https://docs.coveo.com/en/204/) contains sensitive content that shouldn't be visible to everyone, use [source-level permissions](https://docs.coveo.com/en/1779#same-users-and-groups-as-in-your-content-system) to secure your content instead of enforcing the [search hub](https://docs.coveo.com/en/1342/) value in the API key. See [Authenticate commerce requests](https://docs.coveo.com/en/o8ld0051/) for more information. ## Required privileges The following table indicates the [privileges](https://docs.coveo.com/en/228/) required to view or edit elements of the [**API Keys**](https://platform.cloud.coveo.com/admin/#/orgid/organization/api-access/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/organization/api-access/)) page and associated panels (see [Manage privileges](https://docs.coveo.com/en/3151/) and [Privilege reference](https://docs.coveo.com/en/1707/)). [%header,cols=".^2,3,.^3"] |=== |Action |Service - Domain |Required access level |View API keys |Organization - Activities Organization - API keys Organization - Groups |View .2+|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](https://docs.coveo.com/en/1969/). > This member can therefore see all activities taking place in the organization, including those from Coveo Administration Console pages that they can't access.