Activate silently

This is for:

In this article

Prerequisites
Available options
Find the organizationId value
Create 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 operation. Only the Version call is exempted from this.

Find 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

Create an organization

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

You need to specify the organization template for a Coveo for Sitecore trial in the organizationTemplate field. Here are the options:

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

Create the API keys

To configure your Sitecore instance, you’ll need 2 API keys that have different privileges:

The SearchApiKey, for search activities.
The ApiKey, for general organization configuration activities.

To create these API keys, you must use the Coveo Platform API.

Create `SearchApiKey`

Access Coveo Platform API Swagger UI.
Authorize the Swagger UI to perform the upcoming request.
1. At the right of the screen, click the lock icon, and then click Authorize.
2. Authenticate in to the Coveo Platform as an administrator.
In the Parameters section of the Swagger UI, in the organizationId field, enter your organization ID.

In the apiKeyTemplateId field, enter SitecoreCloudSearch.

Note

Creating the key based on the SitecoreCloudSearch template ensures adherence to the principle of minimum privileges and provides future-proofing by transparently applying any changes made to the template privileges to existing API keys.

Copy the following JSON and paste it in the request body:

{
  "displayName": "SearchApiKey",
  "enabled": true
}

Click Execute.
Retrieve the value of the API key from the response body and store it securely.

Create `ApiKey`

Access Coveo Platform API Swagger UI.
If necessary, authorize the Swagger UI to perform the upcoming request.
1. At the right of the screen, click the lock icon, and then click Authorize.
2. Authenticate in to the Coveo Platform as an administrator.
In the Parameters section of the Swagger UI, in the organizationId field, enter your organization ID.

In the apiKeyTemplateId field, enter SitecoreCloudConfiguration.

Note

Creating the key based on the SitecoreCloudConfiguration template ensures adherence to the principle of minimum privileges and provides future-proofing by transparently applying any changes made to the template privileges to existing API keys.

Copy the following JSON and paste it in the request body:

{
  "displayName": "ApiKey",
  "enabled": true
}

Click Execute.
Retrieve the value of the API key from the response body and store it securely.

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