Manage API keys programmatically

This is for:

Developer

In this article

Create an API key programmatically
Rotate an API key programmatically

Developers working on a Coveo-powered deployment may require API keys to interact programmatically with the Coveo Platform. The following are typical situations in which an API key is required:

A developer is working on a search interface that can show both 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 Push API calls.

This article explains how to create and rotate API keys programmatically.

Create an API key programmatically

This section explains how to use the Create API key operation and provides some examples.

You can also create API keys in the Coveo Administration Console on the API Keys (platform-ca | platform-eu | platform-au) page.

Creation request overview

To create an API key with certain privileges in a specific Coveo organization, make the following request to the Coveo Authorization Server API:

POST https://platform.cloud.coveo.com/rest/organizations/<ORGANIZATION_ID>/apikeys?apiKeyTemplateId=<TEMPLATE_ID> HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>

where:

<ORGANIZATION_ID> is the ID of the target Coveo organization.
<TEMPLATE_ID> is the API key template with the right set of privileges for your use case. To create a custom API key, omit this parameter from the request.
<ACCESS_TOKEN> is an OAuth 2.0 access token with administrative privileges in your Coveo organization. Coveo access tokens are valid for four hours.

Payload:

{
  "description": "<API_KEY_DESCRIPTION>", 
  "displayName": "<API_KEY_DISPLAY_NAME>", 
  "allowedIps": [
    <ALLOWED_IP>* 
  ],
  "deniedIps": [
    <DENIED_IP>* 
  ],
  "lifetimeDuration": "<API_KEY_DURATION>", 
  "rotationEnabled": true 
}

	(Optional) Replace `<API_KEY_DESCRIPTION>` with a string that indicates for whom, when, and for what purpose you’re creating the API key. Although this is optional, you should include a detailed description to help manage the key in the future.
	Replace `<API_KEY_DISPLAY_NAME>` with a name that summarizes the key’s purpose. This is optional if you include an API key template in your request. If you omit the `apiKeyTemplateId` parameter to create a custom API key, the `displayName` is mandatory.
	(Optional) Replace `<ALLOWED_IP>*` with a list of IP addresses that should be able to use the API key. For more information, see Allowed and denied IP addresses.
	(Optional) Replace `<DENIED_IP>*` with a list of IP addresses that shouldn’t be able to use the API key. For more information, see Allowed and denied IP addresses.
	If you want to set an expiration date for your key, replace `<API_KEY_DURATION>` with an `ISO 8601^` formatted duration, such as `P30D` for 30 days. This is optional unless you use the View all content template, in which case you must set an expiration date of 1-14 days.
	(Optional) If you want to be able to rotate this API key, you must set this to true when you create the key.

The body of a successful response (201 Created) contains information about the API key you just created. This response includes the following properties, among others:

{
  "id": "xxxxxxxxxxxxxxxxxxxxxxxxxx", 
  "value": "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 
  "organizationId": "<ORGANIZATION_ID>",
  "displayName": "<API_KEY_DESCRIPTION>",
  "description": "<API_KEY_DISPLAY_NAME>",
  "privileges": [ 
    ...
  ],
  "createdDate": 1734516650656,
  "allowedIps": [], 
  "deniedIps": [],
  "apiKeyTemplateId": "<TEMPLATE_ID>", 
  "privacyLevel": "<PRIVACY_LEVEL>", 
  "status": "ENABLED",
  "expirationDate": 1737158399000, 
  "activationDate": 1734516650729,
  "rotationSecret": "coveo_apikey_rotation_v1_xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxxxxxx" 
}

You can use the id property to edit or delete the API key. You can always retrieve this value after an API key has been created.

The value property contains the API key itself.

Copy the key immediately. This is the only time you can see the value of an API key, and you’ll never be able to retrieve it again.

If you fail to save the value, or if you lose it, delete the key and create a new one.

If you created the key using an API key template, the privileges are automatically assigned based on the template. If you created a custom API key, the privileges will match the values that you sent in the payload.

The allowedIps and deniedIps arrays will match the values that you sent in the payload. If you omitted these properties or passed empty arrays in the request, the response will include empty arrays.

If you created the key using a template, this will match the value that you sent in the request. If you created a custom key, this property won’t appear in the response.

The privacy level is based on the template that you used to create the API key. If you created a custom key, this will be PRIVATE.

This property will only appear in the response if you set an expiration date using lifetimeDuration.

This property will only appear in the response if you set rotationEnabled to true. Save this value because you’ll need it to rotate your key in the future.

API key templates

Typically, you’ll use an API key template with predefined privileges, in which case you must specify an apiKeyTemplateId in your request. You can also create a custom API key that doesn’t have any predefined privileges.

The following table lists the apiKeyTemplateId for each template:

Template apiKeyTemplateId

Template	`apiKeyTemplateId`
Anonymous search	`AnonymousSearch`
Authenticated search	`AuthenticatedSearch`
Usage analytics	`UsageAnalytics`
Search pages	`SearchPages`
Anonymous Case Assist	`AnonymousCaseAssist`
Push API	`PushDocument`
View all content	`ViewAllContent`

Anonymous search

AnonymousSearch

Authenticated search

AuthenticatedSearch

Usage analytics

UsageAnalytics

Search pages

SearchPages

Anonymous Case Assist

AnonymousCaseAssist

Push API

PushDocument

View all content

ViewAllContent

Custom API keys

You can create a custom API key by omitting the apiKeyTemplateId from your request. In this case, you’ll have to pass the list of privileges that you want in the request body.

See the example section for a sample custom API key request.

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

Search service
- Execute queries: Allowed
- Impersonate: Allowed
Analytics service
- Analytics data: Push
- Impersonate: Allowed

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

Allowed and denied IP addresses

You can use the allowedIps and deniedIps properties to select which IP addresses can use an API key. The following table lists the results if both, one, or neither property is included in the payload.

Passing an empty allowedIps or deniedIps array has the same result as omitting it from the payload.

allowedIps deniedIps Result

`allowedIps`	`deniedIps`	Result
Yes	Yes	Only the IP addresses in the `allowedIps` array can use the API key, unless they’re also included in the `deniedIps` array.
Yes	No	Only the IP addresses in the `allowedIps` array can use the API key.
No	Yes	Any IP address can use the API key, except for those in the `deniedIps` array.
No	No	Any IP address can use the API key.

Yes

Only the IP addresses in the allowedIps array can use the API key, unless they’re also included in the deniedIps array.

Yes

Only the IP addresses in the allowedIps array can use the API key.

Yes

Any IP address can use the API key, except for those in the deniedIps array.

Any IP address can use the API key.

Examples

Creating an API key for anonymous search:

POST https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/apikeys?apiKeyTemplateId=AnonymousSearch HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Payload:

{
  "description": "Created for Anonymous search on 2024-12-18.",
  "displayName": "Anonymous search key"
}

Successful response - 201 Created (excerpt):

{
  "id": "wduuqg3ip2c3i3gpopapxhcgxe",
  "value": "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "organizationId": "mycoveocloudv2organizationg8tp8wu3",
  "displayName": "Anonymous search key",
  "description": "Created for Anonymous search on 2024-12-18.",
  "privileges": [
    {
      "targetDomain": "EXECUTE_QUERY",
      "targetId": "*",
      "owner": "SEARCH_API"
    },
    {
      "type": "EDIT",
      "targetDomain": "ANALYTICS_DATA",
      "targetId": "*",
      "owner": "USAGE_ANALYTICS"
    }
  ],
  "createdDate": 1734516650656,
  "apiKeyTemplateId": "AnonymousSearch",
  "privacyLevel": "PUBLIC",
  "status": "ENABLED",
  "activationDate": 1734516650729
}

Creating a custom API key to view and edit sources:

POST https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/apikeys HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Payload:

{
  "description": "Created for Alice Smith on 2024-12-18 to view and edit sources.",
  "displayName": "Source Edit/View",
  "privileges": [ 
    {
      "owner": "PLATFORM",
      "targetDomain": "SOURCE",
      "type": "EDIT"
    },
    {
      "owner": "PLATFORM",
      "targetDomain": "SOURCE",
      "type": "VIEW"
    }
  ]
}

For each privilege you include in the privileges array, specify a valid owner, targetDomain, and type combination.

Successful response - 201 Created (excerpt):

{
  "id": "wduuqg3ip2c3i3gpopapxhcgxe",
  "value": "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "organizationId": "mycoveocloudv2organizationg8tp8wu3",
  "displayName": "Source Edit/View",
  "description": "Created for Alice Smith on 2024-12-18 to view and edit sources.",
  "privileges": [
    {
      "type": "EDIT",
      "targetDomain": "SOURCE",
      "targetId": "*",
      "owner": "PLATFORM"
    },
    {
      "type": "VIEW",
      "targetDomain": "SOURCE",
      "targetId": "*",
      "owner": "PLATFORM"
    }
  ],
  "createdDate": 1734516650656,
  "privacyLevel": "PRIVATE",
  "status": "ENABLED",
  "activationDate": 1734516650729
}

Rotate an API key programmatically

This section explains how to use the Rotate API key operation.

When you rotate an API key programmatically, the original key is automatically set to expire. Furthermore, you can only rotate a given key once, because the rotation secret becomes invalid afterward.

You can also rotate an API key by creating a new key from an existing key in the Coveo Administration Console on the API Keys (platform-ca | platform-eu | platform-au) page.

Rotation prerequisites

You can rotate an API key if it meets the following prerequisites:

When the key was created, the rotationEnabled field was set to true, and you retained the rotationSecret value that you received in the response.

The key that you want to rotate hasn’t been deleted and isn’t deactivated or expired.

Note

API keys with the Soon to be deactivated, Soon to be expired, or Exposed status can be rotated programmatically.

If you need to rotate a deactivated or expired key, you can create a new key from an existing key in the Coveo Administration Console on the API Keys (platform-ca | platform-eu | platform-au) page.

Rotation request overview

To rotate an API key, make the following request to the Authorization Server API:

POST https://platform.cloud.coveo.com/rest/organizations/<ORGANIZATION_ID>/apikeys/rotate HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer <API_KEY>

where:

<ORGANIZATION_ID> is the ID of the target Coveo organization.
<API_KEY> is the value of the API key that you want to rotate.

You must authenticate this request using the API key itself, not a Coveo access token.

Payload:

{
  "rotationSecret": "coveo_apikey_rotation_v1_<UUID>_<CRC32>", 
  "previousKeyExpirationPeriod": "P14D", 
  "newKeyExpirationPeriod": "P30D" 
}

	This is the rotation secret that was in the response when you created the original API key.
	(Optional) After you rotate an API key, the original key will expire in 30 days or less. Use `previousKeyExpirationPeriod` to set or change the expiration date of your original key. This must be in `ISO 8601^` duration format, such as `P30D` for 30 days.
	(Optional) The new API key won’t have an expiration date by default, even if the original key had one. Use `newKeyExpirationPeriod` to set an expiration date of up to 1 year. This must be in `ISO 8601^` duration format, such as `P1Y` for 1 year.

The body of a successful response (200 OK) contains information about the new API key you created. This response includes the following properties, among others:

{
  "id": "xxxxxxxxxxxxxxxxxxxxxxxxxx", 
  "value": "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "organizationId": "<ORGANIZATION_ID>",
  "displayName": "<API_KEY_DESCRIPTION>",
  "description": "<API_KEY_DISPLAY_NAME>",
  "privileges": [
    ...
  ],
  "createdDate": 1734516650656,
  "allowedIps": [],
  "deniedIps": [],
  "apiKeyTemplateId": "<TEMPLATE_ID>",
  "privacyLevel": "<PRIVACY_LEVEL>",
  "status": "ENABLED",
  "expirationDate": 1737158399000, 
  "activationDate": 1734516650729,
  "rotationSecret": "coveo_apikey_rotation_v1_xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_xxxxxxxx" 
}

	The new API key will have a different `id` and `value` from the original key. Most of the other properties will be the same as those of the original key, and the new key will have the same privileges.
	This property will only appear in the response if you set an expiration date using `newKeyExpirationPeriod`.
	A new `rotationSecret` will let you rotate this key in the future.

Rotation and API key expiration

When you rotate an API key, the original key will be set to expire in 30 days or less, depending on its initial expiration date. You can use the previousKeyExpirationPeriod property in the request body to set a specific expiration date for the original key, as in the following table:

Expiration date Possible values for previousKeyExpirationPeriod If you don’t set previousKeyExpirationPeriod

Expiration date	Possible values for `previousKeyExpirationPeriod`	If you don’t set `previousKeyExpirationPeriod`
None	Between 1 day and 30 days.	The original key expires in 30 days.
> 30 days
<= 30 days	Between 1 day and the existing expiration date.	The original key keeps its existing expiration date.

None

Between 1 day and 30 days.

The original key expires in 30 days.

> 30 days

<= 30 days

Between 1 day and the existing expiration date.

The original key keeps its existing expiration date.