Create an API key programmatically

This is for:

In this article

Sample request

In the context of the Coveo Platform, an API key is an access token carrying a certain set of privileges in a specific Coveo organization. Anyone with an authorized IP address can use an API key to authenticate REST API calls for which this key grants the required privileges.

Use the Create a new API key for this organization operation to create an API key with certain privileges in a specific Coveo organization.

Alternatively, you can create an API key in the Coveo Administration Console, on the API Keys (platform-ca | platform-eu | platform-au) page.

Request template:

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

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

where:

<MyOrganizationId> is the ID of the target Coveo organization
<MyAccessToken> is an access token (API key or OAuth 2.0 token) that grants you the EDIT API_KEY privilege in the target organization. See Get the privileges of an access token for more information.

Payload:

{
  "allowedIps": [
    <MyAllowedIP>* 
  ],
  "deniedIps": [
    <MyDeniedIP>* 
  ],
  "description": "<MyAPIKeyDescription>", 
  "displayName": "<MyAPIKeyDisplayName>", 
  "enabled": "<true|false>", 
  "privileges": [ 
    {
      "owner": "<USAGE_ANALYTICS>|<PLATFORM>|<SEARCH_API>",
      "targetDomain": "<ValidDomain>",
      "type": "<VIEW>|<EDIT>"
    }
  ]
}

In the allowedIps array of the request body, for each IP address that should be able to use the API key, replace <MyAllowedIP>* with this IP address. If you pass an empty allowedIps array, or if you don’t include the allowedIps property at all, any IP address not in the deniedIps array will be able to use the API key. Otherwise, only IP addresses in the allowedIps array and not in the deniedIps array will be able to use the API key.

In the deniedIps array, for each IP address that shouldn’t be able to use the API key, replace <MyDeniedIP>* with this IP address. If you pass an empty deniedIps array, or if you don’t include the deniedIps property at all, any IP address will be able to use the API key unless the allowedIps array contains IP addresses.

Replace <MyAPIKeyDescription> with a string indicating for whom, when, and for what purpose you’re creating the API key.

Replace <MyAPIKeyDisplayName> with an adequate name, summarizing the API key purpose.

Leading practice

Although optional, specifying relevant values for the displayName and description properties will greatly help whoever manages API keys in the target Coveo organization, if not already done.

Set the enabled property to true in the request body when you want the new API key to work right away. Otherwise, set it to false.

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

The body of a successful response (201 Created) contains information about the API key you have just created.

You can use the id property to later edit or delete the API key. You can always get this value back once the API key has been created.

The value property contains the API key itself.

The API key creation call response body is your unique occasion to get the API key value. It’s impossible to get it again.

If you fail to get the value, delete the lost key, and create a new one.

Sample request

Creating an 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 2017-12-18 to view and edit sources in the context of a Coveo tutorial.",
  "displayName": "Source Edit/View",
  "enabled": true,
  "privileges": [
    {
      "owner": "PLATFORM",
      "targetDomain": "SOURCE",
      "type": "EDIT"
    },
    {
      "owner": "PLATFORM",
      "targetDomain": "SOURCE",
      "type": "VIEW"
    }
  ]
}

Successful response - 201 Created:

{
  "id": "wduuqg3ip2c3i3gpopapxhcgxe",
  "value": "xx590a182c-5045-4914-a00b-1f4099581b3e",
  "organizationId": "mycoveocloudv2organizationg8tp8wu3",
  "displayName": "Source Edit/View",
  "description": "Created for Alice Smith on 2017-12-18 to view and edit sources in the context of a Coveo tutorial.",
  "privileges": [
    {
      "type": "EDIT",
      "targetDomain": "SOURCE",
      "targetIds": [],
      "owner": "PLATFORM"
    },
    {
      "type": "VIEW",
      "targetDomain": "SOURCE",
      "targetIds": [],
      "owner": "PLATFORM"
    }
  ]
}