Create an API key programmatically

This is for:

System Administrator
In this article

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

You can also perform this action from the Coveo Administration Console (see Manage API Keys - Add an API key ).

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>

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 request path:

In the Authorization HTTP header:

In the request body:

  • In the allowedIps array, 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.

    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; set it to false otherwise.

  • For each privilege you include in the privileges array:

The body of a successful response (201 Created) contains information about the API key you 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 (see Get the apiKeyId).

  • 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 (see Delete an API key).

Sample request

Request Example - 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"
    }
  ]
}