Activate silently

This is for:

In this article

Prerequisites
Available options
Finding the OrganizationId value
Creating the API keys

In some circumstances, for example when creating many Sitecore servers, you’ll want to silently activate and configure Coveo for Sitecore. This can be done using a REST API to set the different configuration usually entered on the Command Center Activation page.

You can also see the documentation for the provided calls by accessing the Swagger UI available under http://<INSTANCE_HOSTNAME>/coveo/api/config/docs/index.

Swagger UI for Configuration and Activation services | Coveo

Prerequisites

A running instance of Sitecore.

Note

For an extensive list of Sitecore supported versions, see Supported Sitecore Versions and Dependencies.

ASP.NET MVC 4.0 or MVC 5.0 installed on your Sitecore server:

Note

To configure MVC while installing Sitecore, see Sitecore MVC Developer’s Reference Guide. If you have already installed Sitecore and you now want to enable MVC manually, see Sitecore MVC Playground Part 1: Enable MVC.

Available options

The Swagger endpoint provides the following options:

Organization endpoints

Coveo for Sitecore 5.0.1277.4

Using organization endpoints is the recommended Coveo for Sitecore configuration.

The organizations/organizationendpoints GET call retrieves the search (that is, the DistributedDns), admin, and analytics organization endpoints you can use to configure Coveo for Sitecore.

The call requires:

Your ApiKey as the x-AccessToken value
Your organizationId
The platformEndpoint
Your Sitecore instance administrator credentials.

Configure

The configure PUT call is used to set the different values needed for the Coveo for Sitecore configuration, for example the OrganizationId and ApiKey.

If you’re running the May 9, 2023 (5.0.1227.1) release or later, you can use the configure PUT call to enable organization endpoints. See the PowerShell command usage example placeholder descriptions for more information on the endpoint URLs to use.

Activate

The activate POST call is used to activate Coveo for Sitecore on the Sitecore instance. This will rename the base .example config files that come with Coveo for Sitecore to enable them.

It will also validate that all the values required have been set with configure previously.

Version

The Version call is available under http://<INSTANCE_HOSTNAME>/coveo/api/config/version and returns that latest version of the API.

This version is used in the URL to call the other operations, for example coveo/api/config/v1/configure. Make sure to always use a specific version in your client implementation to avoid breaking changes in future versions.

Authentication

An authentication needs to be provided using the x-scUsername and x-scPassword headers for each API operations. Only the Version call is exempted from this.

Finding the OrganizationId value

The OrganizationId can be retrieved in the URL of your Coveo organization.

OrganizationId shown in the URL of your Coveo organization | Coveo

Creating an organization

If you don’t have access to an existing organization, you can create a trial organization through the Platform API.

You need to specify the organization template for a Coveo for Sitecore trial, here are the options:

SitecoreCloudProEditionTrial for the Pro edition.
SitecoreCloudTrialEdition for the Enterprise edition.

Creating the API keys

To configure your Sitecore instance, you’ll need 2 API keys that have different privileges: one for search activities (SearchApiKey) and the other for general configuration activities of your organization (ApiKey).

To create these API keys, you can either use the Cloud Platform API or the Coveo Administration Console (platform-ca | platform-eu | platform-au) (see Manage API keys).

Privileges for the SearchApiKey

When using the Cloud Platform API

The SearchApiKey needs the following privilege:

owner targetDomain type Coveo Administration Console equivalent

owner	targetDomain	type	Coveo Administration Console equivalent
`SEARCH_API`	`IMPERSONATE`		Search - Impersonate - Allowed

SEARCH_API

IMPERSONATE

Search - Impersonate - Allowed

The payload of your call to the Cloud Platform API must look like the following:

{
  "displayName": "SearchApiKey",
  "privileges": [
    {
      "targetDomain": "IMPERSONATE",
      "owner": "SEARCH_API"
    }
  ],
  "enabled": true
}

Retrieve the SearchApiKey value from the response of the call and store it securely.

When adding a key from the API Keys (platform-ca | platform-eu | platform-au) page in the Coveo Administration Console

The SearchApiKey needs the following privilege:

SearchApiKey required Search privileges | Coveo

You must also limit the scope of your SearchApiKey to a specific search hub.

Privileges for the ApiKey

When using the Cloud Platform API

The ApiKey needs the following privileges:

owner targetDomain type Coveo Administration Console equivalent

owner	targetDomain	type	Coveo Administration Console equivalent
`PLATFORM`	`FIELD`	`VIEW`, `EDIT`	Content - Fields - Edit
`PLATFORM`	`SECURITY_CACHE`	`VIEW`, `EDIT`	Content - Security identities - Edit
`PLATFORM`	`SECURITY_PROVIDER`	`VIEW`, `EDIT`	Content - Security identity providers - Edit
`PLATFORM`	`SOURCE`	`VIEW`, `EDIT`	Content - Sources - Edit all
`PLATFORM`	`ORGANIZATION`	`VIEW`, `EDIT`	Organization - Organization - Edit
`SEARCH_API`	`SEARCH_PAGES`	`VIEW`	Search - Search pages - View

PLATFORM

FIELD

VIEW, EDIT

Content - Fields - Edit

PLATFORM

SECURITY_CACHE

VIEW, EDIT

Content - Security identities - Edit

PLATFORM

SECURITY_PROVIDER

VIEW, EDIT

Content - Security identity providers - Edit

PLATFORM

SOURCE

VIEW, EDIT

Content - Sources - Edit all

PLATFORM

ORGANIZATION

VIEW, EDIT

Organization - Organization - Edit

SEARCH_API

SEARCH_PAGES

VIEW

Search - Search pages - View

The payload of your call to the Cloud Platform API must look like the following:

{
  "displayName": "ApiKey",
  "privileges": [
    {
      "targetDomain": "FIELD",
      "owner": "PLATFORM",
      "type": "EDIT"
    },
    {
      "targetDomain": "FIELD",
      "owner": "PLATFORM",
      "type": "VIEW"
    },
    {
      "targetDomain": "SECURITY_CACHE",
      "owner": "PLATFORM",
      "type": "EDIT"
    },
    {
      "targetDomain": "SECURITY_CACHE",
      "owner": "PLATFORM",
      "type": "VIEW"
    },
    {
      "targetDomain": "SECURITY_PROVIDER",
      "owner": "PLATFORM",
      "type": "EDIT"
    },
    {
      "targetDomain": "SECURITY_PROVIDER",
      "owner": "PLATFORM",
      "type": "VIEW"
    },
    {
      "targetDomain": "SOURCE",
      "owner": "PLATFORM",
      "type": "EDIT"
    },
    {
      "targetDomain": "SOURCE",
      "owner": "PLATFORM",
      "type": "VIEW"
    },
    {
      "targetDomain": "ORGANIZATION",
      "owner": "PLATFORM",
      "type": "EDIT"
    },
    {
      "targetDomain": "ORGANIZATION",
      "owner": "PLATFORM",
      "type": "VIEW"
    },
    {
      "targetDomain": "SEARCH_PAGES",
      "owner": "SEARCH_API",
      "type": "VIEW"
    }
  ],
  "enabled": true
}

Retrieve the ApiKey value from the response of the call and store it securely.

When adding a key from the API Keys (platform-ca | platform-eu | platform-au) page in the Coveo Administration Console

The ApiKey needs the following privileges:

ApiKey required Content privileges | Coveo

ApiKey required Organization privileges | Coveo

ApiKey required Search privileges | Coveo

Sitecore on Azure

Azure’s Web Application Firewall (WAF) may block Coveo query network calls that trigger OWASP rules. You might need to disable or customize Azure WAF rules to allow Coveo for Sitecore network calls (see Azure Web Application Firewall triggered rules block Coveo for Sitecore’s communication on Content Delivery servers).