Creating an API Key

In the context of the Coveo Cloud platform, an API key is an access token carrying a certain set of privileges in a specific Coveo Cloud 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 Cloud organization.

Request template

POST https://platform.cloud.coveo.com/rest/organizations/<MyOrganizationId>/apikeys HTTP/1.1
 
Accept: application/json
Content-Type: application/json
Authorization: Bearer <MyOAuth2Token>

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 do not 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 should not be able to use the API key, replace <MyDeniedIP>* with this IP address. If you pass an empty deniedIps array, or if you do not 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 are 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 Cloud organization.

  • 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 Getting 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 is impossible to get it again.

    If you fail to get the value, delete the lost key, and create a new one (see Deleting 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 Cloud platform 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 Cloud platform tutorial.",
  "privileges": [
    {
      "type": "EDIT",
      "targetDomain": "SOURCE",
      "targetIds": [],
      "owner": "PLATFORM"
    },
    {
      "type": "VIEW",
      "targetDomain": "SOURCE",
      "targetIds": [],
      "owner": "PLATFORM"
    }
  ]
}