---
title: "Configure API authentication keys in a scaled environment"
slug: "configure-api-authentication-keys-in-a-scaled-environment"
abstract: "How to configure API authentication keys on the Sitecore xDB Reporting service and the xDB Processing server."
---
# Configure API authentication keys in a scaled environment

| **Applies to** | xDB Processing, xDB Reporting and Content Management. |
| --- | --- |
| **Sitecore Installation Framework** | Security keys are **not** configured by default. |
| **Azure Toolkit** | Security keys are configured by default when they are entered into the ARM template. |

To ensure secure communication between servers in a scaled Sitecore environment, each request from a client must be authenticated on the xDB Reporting server and the xDB Processing server. For example, on a Content Management server that needs to communicate with a remote Reporting server. In scaled environments, only authenticated parties can gain access to data on remote servers.

For each server request, the `Sitecore.Analytics.Commons.ApiKeyHttpTransportFactory` class adds a custom HTTP header to the page requested. The header includes an API authentication key, which is stored in the ConnectionStrings.config file.

On each server you must enter an API authentication key that can be used during the authentication process. Keys must be identical to successfully authenticate requests. For example, the key on a Reporting server must match the key stored on a content management server to successfully retrieve data from the Reporting.

![communication-between-cm-and-reporting1.png](https://doc.sitecore.com/api/markdown-image/xp/en/developers/100/platform-administration-and-architecture/images/communication-between-cm-and-reporting1.png)

The server authentication process is as follows:

- A Content Management client requests data from the Reporting server using the `Sitecore.Analytics.Commons.ApiKeyHttpTransportFactory` class.
- When the Reporting server receives the request, the `ApiKeyReportDataProvider` class checks that the API authentication key from the HTTP header matches (case-sensitive) the one stored on the Reporting server.
- If the two keys match, the processing of the request can continue, data is retrieved and can be sent back to the Content Management client.
- If the authentication keys do not match, the server responds with a 403 (Forbidden) status code.

> [!important]
> Use HTTPS across your entire website. In the `Sitecore.Xdb.Remote.Client.config` file, `RequireHttps` is enabled by default and should remain enabled in all production environments. HTTP is not secure enough for production servers and should only be used on local testing or development instances.

## Option #1: Configure a shared API authentication key

The following section describes how to configure an API authentication key between the Content Management and the Processing and Reporting servers. In this scenario, Processing and Reporting use the same authentication key.

### On the Content Management server

To configure an API authentication key on the Content Management server:

1. On the Content Management server, navigate to the `Website\App_Config` folder and open the `ConnectionString.config` file.
2. In the `ConnectionStrings.config` file, find the `reporting.apikey` connection string and enter an ASCII string to use as a key (default minimum length 32 characters). The key can be any combination of numerals or text.

    For example:

    ```text
    <add name="reporting.apikey" connectionString="67588d50667e47e0a02cb919185f7c30"/>
    ```

    > [!important]
    > The string you choose must conform to the minimum API key length as specified in the `Sitecore.Xdb.Remote.Client.config` file, `MinimalApiKeyLength` attribute.

### On the Processing and Reporting servers

To configure an API authentication key on the Processing and Reporting servers:

1. On the Processing and Reporting servers, navigate to the `Website\App_Config` folder and open the `ConnectionStrings.config` file.
2. Add the `reporting.apikey` connection string to the `ConnectionStrings.config` file. The key must match the Content Management server.

## Option #2: Configure a separate API authentication key for Processing

The following section describes how to configure different API authentication keys between Content Management and Processing, and Content Management and Reporting.

### On the Content Management server

On the Content Management server, or any other server that is making the request for data from the Processing server:

1. In the `Sitecore.Xdb.Remote.Client.config` file, locate the following section and set the `connectionStringName` parameter to a new value - for example, `processing.apikey`:

    ```xml
    <processing>
        <remote enabled="true">
            <reportingStorageManagerProxy type="Sitecore.Analytics.Aggregation.History.Remoting.ReportingStorageManagerProxy, Sitecore.Analytics.Aggregation">
                <param desc="serviceLocation">/~/v81/processing/reportingstoragemanager/</param>
                <param desc="webTransportFactory" ref="processing/remote/httpTransportFactory" />
            </reportingStorageManagerProxy>
            <httpTransportFactory type="Sitecore.Analytics.Core.ApiKeyHttpTransportFactory, Sitecore.Analytics.Core" singleInstance="true">
                <param desc="serviceUrl"></param>
                <param desc="requireHttps" type="System.Boolean" factoryMethod="Parse" arg0="true" />
                <param desc="connectionStringName">processing.apikey</param>
                <!-- The same header name must be defined in Sitecore.Xdb.Remote.Server.config for reporting.-->
                <param desc="headerName">X-Processing-Api-Key</param>
                <param desc="minimalApiKeyLength">32</param>
            </httpTransportFactory>
        </remote>
    </processing>
    ```

2. Add two API authentication keys to the `ConnectionStrings.config` file:

    For example:

    ```xml
    <add name="reporting.apikey" connectionString="24588d50667e47e0a02cb919185f7c30"/>
    <add name="processing.apikey" connectionString="90588d50667e47e0a02cb919185f7c30"/>
    ```

### On the Processing server

To configure an API authentication key on the Processing server:

1. In the `Sitecore.Xdb.Remote.Client.config` file, locate the following section and update the `connectionStringName` parameter as shown:

    ```xml
    <processing role:require="Processing">
        <authenticationChecker singleInstance="true" type="Sitecore.Xdb.Reporting.HttpHeaderAuthenticationChecker, Sitecore.Xdb.Reporting">
            <!-- The same header name must be defined in Sitecore.Xdb.Remote.Client.config for CM instance.-->
            <param desc="headerName">X-Processing-Api-Key</param>
            <param desc="connectionStringName">processing.apikey</param>
            <param desc="logger" resolve="true" type="Sitecore.Abstractions.BaseLog, Sitecore.Kernel" />
        </authenticationChecker>
    </processing>
    ```

2. Add a new API authentication key to the `ConnectionStrings.config` file:

    ```text
    <add name="processing.apikey" connectionString="90588d50667e47e0a02cb919185f7c30"/>
    ```

3. Remove the `reporting.apikey` from the `ConnectionStrings.config` file if it is present.

### On the Reporting server

To configure an API authentication key on the Reporting server:

- Add a new API authentication key to the `ConnectionStrings.config` file:

    ```text
    <add name="reporting.apikey" connectionString="24588d50667e47e0a02cb919185f7c30"/>
    ```

## Optional configuration

### Optional Content Management server configuration

The following table shows the default parameter settings in the `Sitecore.Xdb.Remote.Client.config` file that you can adjust later, if necessary. You can configure different parameter settings for Processing and Reporting.

> [!note]
> If you're running Sitecore on Azure, the settings are in the `App_Config/Sitecore/Azure/Sitecore.Xdb.Remote.Client.CM.config` file.

| Parameter | Description |
| --- | --- |
| ServiceUrl | The service host URL to use in all requests. Update this if the host name of your reporting server changes. |
| ConnectionStringName | The name of the connection string that contains the API authentication key. |
| HeaderName | The name of the header to include in the request. Use the same header name on both servers. For example, X-Reporting-Api-Key. |
| MinimalApiKeyLength | This specifies a minimum key length for the API authentication key. If it is too short, then the request will not be sent. Longer keys are more secure. |
| RequireHttps | Boolean switch set to “true” by default. Always use HTTPS in a production environment. If it is set to “true” and the schema in <paramref name=”serviceHostUrl”/> is not HTTPS, an exception will be thrown. |

These configuration parameters appear in the following section of the `Sitecore.Xdb.Remote.Client.config` file:

```xml
<reporting>
    <remote enabled="true">
        <httpTransportFactory type="Sitecore.Analytics.Core.ApiKeyHttpTransportFactory, Sitecore.Analytics.Core" singleInstance="true">
            <param desc="serviceUrl"></param>
            <param desc="requireHttps" type="System.Boolean" factoryMethod="Parse" arg0="true" />
            <param desc="connectionStringName">reporting.apikey</param>
            <!-- The same header name must be defined in Sitecore.Xdb.Remote.Server.config for reporting.-->
            <param desc="headerName">X-Reporting-Api-Key</param>
            <param desc="minimalApiKeyLength">32</param>
        </httpTransportFactory>
        <proxyDataSource type="Sitecore.Xdb.Reporting.Datasources.Remote.RemoteReportDataSourceProxy, Sitecore.Xdb.Reporting" />
        <path>/~/v75/reporting/remotedatasourceproxy/</path>
    </remote>
</reporting>
<processing>
    <remote enabled="true">
        <reportingStorageManagerProxy type="Sitecore.Analytics.Aggregation.History.Remoting.ReportingStorageManagerProxy, Sitecore.Analytics.Aggregation">
            <param desc="serviceLocation">/~/v81/processing/reportingstoragemanager/</param>
            <param desc="webTransportFactory" ref="processing/remote/httpTransportFactory" />
        </reportingStorageManagerProxy>
        <httpTransportFactory type="Sitecore.Analytics.Core.ApiKeyHttpTransportFactory, Sitecore.Analytics.Core" singleInstance="true">
            <param desc="serviceUrl"></param>
            <param desc="requireHttps" type="System.Boolean" factoryMethod="Parse" arg0="true" />
            <param desc="connectionStringName">reporting.apikey</param>
            <!-- The same header name must be defined in Sitecore.Xdb.Remote.Server.config for reporting.-->
            <param desc="headerName">X-Processing-Api-Key</param>
            <param desc="minimalApiKeyLength">32</param>
        </httpTransportFactory>
    </remote>
</processing>

```

### Optional Reporting server configuration

On the Reporting server, the `Sitecore.Analytics.Reporting.ApiKeyReportDataProvider` is defined in the `<dataProvider>` configuration section of the` Sitecore.Xdb.Remote.Server.config` file. The `Sitecore.Xdb.Remote.Server.config` file contains the following default parameters:

| Parameter | Description |
| --- | --- |
| ConnectionStringName | The name of the connection string that contains the correct API authentication key (this should match the key of the server making the request). |
| HeaderName | The name of the header to check in the incoming server request. |

These configuration parameters appear in the following section of the `Sitecore.Xdb.Remote.Client.config` file:

```xml
<reporting role:require="Reporting">
    <authenticationChecker singleInstance="true" type="Sitecore.Xdb.Reporting.HttpHeaderAuthenticationChecker, Sitecore.Xdb.Reporting">
        <!-- The same header name must be defined in Sitecore.Xdb.Remote.Client.config for CM instance.-->
        <param desc="headerName">X-Reporting-Api-Key</param>
        <param desc="connectionStringName">reporting.apikey</param>
        <param desc="logger" resolve="true" type="Sitecore.Abstractions.BaseLog, Sitecore.Kernel" />
    </authenticationChecker>
</reporting>

```

### Optional Processing server configuration

| Parameter | Description |
| --- | --- |
| ConnectionStringName | The name of the connection string that contains the correct API authentication key (this should match the key of the server making the request). |
| HeaderName | The name of the header to check in the incoming server request. |

```xml
<processing role:require="Processing">
    <authenticationChecker singleInstance="true" type="Sitecore.Xdb.Reporting.HttpHeaderAuthenticationChecker, Sitecore.Xdb.Reporting">
        <!-- The same header name must be defined in Sitecore.Xdb.Remote.Client.config for CM instance.-->
        <param desc="headerName">X-Processing-Api-Key</param>
        <param desc="connectionStringName">processing.apikey</param>
        <param desc="logger" resolve="true" type="Sitecore.Abstractions.BaseLog, Sitecore.Kernel" />
    </authenticationChecker>
</processing>

```