> For the complete documentation index, see [llms.txt](https://developers.didomi.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.didomi.io/api-and-platform/domains/reverse-proxy.md).

# Reverse proxy

A reverse proxy is a method by which your organization can configure a custom domain to serve the Didomi SDKs and API assets through its own domain. When configured, a reverse proxy will route all traffic to your custom domain to your organization's inrastructure first before it is proxied Didomi. It will also allow your organization to do caching and traffic management.

Some benefits of implementing a custom domain via reverse proxy include:

* Enhanced performance by leveraging Cloud and Edge providers' caching functionalities
* Maintain brand consistency and reduce reliance on third-party domains.
* Potentially improve compliance with privacy regulations by controlling SDK delivery.

In this article, we will cover the following in regards to your reverse proxy implementation

* [Main domain vs sub-domain implementation](#main-domain-vs-subdomain-implementation)
* [Guidelines](#guidelines)
* [Implementation guides](#implementation-guides)

***

## Main domain vs Subdomain Implementation

When implementing a reverse proxy for the Didomi SDK and its API events, your organization will need to decide between using its main domain or a dedicated subdomain.

<table><thead><tr><th width="196">Implementation</th><th></th></tr></thead><tbody><tr><td>Main domain</td><td>Serves the SDK through as a subpath on your primary domain (e.g., <code>domain.com/consent/*</code> or <code>www.domain.com/consent/*</code>) that users access your website on.</td></tr><tr><td>Dedicated subdomain</td><td>Serves the SDK through a separate subdomain (e.g., <code>sub.domain.com</code>) directed to the Didomi CMP.</td></tr></tbody></table>

## Guidelines

In this section, we provide guidelines for how your organization can implement reverse proxy for either your organization's main domain or a dedicated subdomain.

* [Proxy Didomi endpoints](#proxy-didomi-endpoints)
* [Implementation](#implementation)

{% hint style="info" %}
Please see our [implementation guides](#implementation-guides) to see if we provide dedicated resources for your organization's specific platform.
{% endhint %}

### Proxy Didomi endpoints

Regardless of whether your organization configures a reverse proxy for its main domain or a dedicated subdomain, you will want to proxy the relevant endpoints for:

* [Didomi SDK](#web-sdk)
* [Didomi API](#api)

{% tabs %}
{% tab title="SDK" %}
The Didomi SDKs are served on `sdk.privacy-center.org` and is composed of the following files:

{% hint style="warning" %}
**Note**: Didomi does not guarantee the number of files nor the structure of their paths as these can change when the SDK is updated to add new regulations or features, and optimize the loading process.

**Do not try to whitelist specific files to cache: all files from the `sdk.privacy-center.org` domain should be proxied and cached without any filtering by your organization.**
{% endhint %}

<table><thead><tr><th width="87">Name</th><th width="191">Update frequency</th><th width="98">Cache lifetime</th><th>Description</th></tr></thead><tbody><tr><td>Loader</td><td>Every time a new version of the consent notice is published or when Didomi releases a new version of the Web SDK (up to a few times a week).</td><td>Short (from minutes up to 1 hour)</td><td>Dynamic file that contains the configuration of consent notices. The file is specific to every organization and notice.<br><br><strong>Pattern:</strong><br><code>https://sdk.privacy-center.org/{Public API Key}/loader.js</code></td></tr><tr><td>Core</td><td>When Didomi releases a new version of the Web SDK (up to a few times a week).</td><td>Long (1 year)</td><td>Static JavaScript file that contains the logic of the SDK.<br><br><strong>Pattern:</strong><br><code>https://sdk.privacy-center.org/sdk/{Version ID}/.sdk.{Version ID}.{Browser support}.js</code></td></tr><tr><td>UI</td><td>When Didomi releases a new version of the Web SDK (up to a few times a week).</td><td>Long (1 year)</td><td><p>Static JavaScript files that contain all the UI of the SDK.<strong>:</strong></p><p><strong>Patterns:</strong></p><ul><li><code>https://sdk.privacy-center.org/sdk/{Version ID}/ui-{Regulation}-{Language}-web.{Version ID}.{Browser support}.js</code> (for GDPR and other regulations with multiple languages)</li><li><code>https://sdk.privacy-center.org/sdk/{Version ID}/ui-ccpa.{Version ID}.{Browser support}.js</code></li><li><code>https://sdk.privacy-center.org/sdk/{Version ID}/ui-cpa.{Version ID}.{Browser support}.js</code></li><li><code>https://sdk.privacy-center.org/sdk/{Version ID}/ui-cpra.{Version ID}.{Browser support}.js</code></li><li><code>https://sdk.privacy-center.org/sdk/{Version ID}/ui-ctdpa.{Version ID}.{Browser support}.js</code></li><li><code>https://sdk.privacy-center.org/sdk/{Version ID}/ui-vcdpa.{Version ID}.{Browser support}.js</code></li><li><code>https://sdk.privacy-center.org/sdk/{Version ID}/iab-texts.{Version ID}.{Browser support}.js</code> (IAB vendor information)</li></ul></td></tr></tbody></table>
{% endtab %}

{% tab title="API" %}
The Didomi API is available on `api.privacy-center.org`. All requests sent to the API must be proxied to the domain without any caching.
{% endtab %}
{% endtabs %}

### Implementation

Select the tabs below below to learn more about implementing reverse proxy on your organization's main domain or dedicated subdomain

{% tabs %}
{% tab title="Domain" %}
In this tab, we will cover the implementation steps needed specific to configuring a reverse proxy for your organization's main domain.

* [Configure reverse proxy](#configure-reverse-proxy)
* [Add end-user country and region](#add-end-user-country-and-region)

#### Configure reverse proxy

{% hint style="info" %}
We will use `client.com/consent/` as an example in this article.
{% endhint %}

{% stepper %}
{% step %}
The proxy must query the Didomi URL in HTTPS for all files from `https://client.com/consent/` to `https://sdk.privacy-center.org` with their associated path, method, headers, and body.

{% hint style="info" %}
For instance, the request `GET https://client.com/consent/loader.js?domain=...` should be proxied to `GET https://sdk.privacy-center.org/loader.js?domain=...`
{% endhint %}
{% endstep %}

{% step %}
The proxy must query the Didomi URL in HTTPS for all requests to `https://client.com/consent/api/` to `https://api.privacy-center.org` with their associated path, method, headers, and body.

{% hint style="info" %}
For instance, the request `POST https://client.com/consent/api/events` should be proxied to `POST https://api.privacy-center.org/events`.
{% endhint %}
{% endstep %}
{% endstepper %}

#### Add end-user country and region

In addition to the above rules, your organization will need to add the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country and [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) region code to your notice configuration on page load to ensure that the correct `loader.js` file is downloaded from our services to be cached by your proxy correctly.

Add the user country and region directly to your local SDK config object during page load, dynamically setting the `window.didomiConfig.user.country` and `window.didomiConfig.user.region` properties to have their values equal to a valid country and region codes. These settings will override the default geolocation behavior on the `loader.js` route.

{% code overflow="wrap" %}

```javascript
window.didomiConfig = {
    user: {
        country: "US",
        region: "CA"
    }
}
```

{% endcode %}

In the example above, an end-user located in California, USA who loads the SDK will end up making a request to the Didomi CDN with `country=US` and `region=CA` parameters at load time.

**Example**

{% code overflow="wrap" %}

```
https://client.com/consent/{public API key}/loader.js?target_type=notice&target=4QS9p3Qn&country=US&region=CA
```

{% endcode %}

The request will be proxied to: `https://sdk.privacy-center.org/{public API key}/loader.js?target_type=notice&target=4QS9p3Qn&country=US&region=CA`

{% hint style="info" %}
[Click here](https://developers.didomi.io/cmp/web-sdk/consent-notice/notice/behavior#configuration-by-user-country) for more information on leveraging the `didomiConfig` object for controlling the behavior of an end-user's location. Please note that this may require obtaining a new embed code for your notice and updating the embed code in your HTML if your consent notice was created earlier than September 2023.
{% endhint %}
{% endtab %}

{% tab title="Subdomain" %}
In this tab, we will cover the implementation steps needed specific to configuring a reverse proxy for a dedicated subdomain.

* [Create dedicated subdomain](#create-dedicated-subdomain)
* [Configure reverse proxy](#configure-reverse-proxy)
* [Add end-user country and region](#add-end-user-country-and-region-1)

#### Create dedicated subdomain

Create a dedicated sub-domain and point it to your reverse proxy.

{% hint style="info" %}
We will use `dsdk.client.com` as an example in this article but any subdomain that your organization creates will work.
{% endhint %}

#### Configure reverse proxy

Using the reverse proxy software of your choice, apply the following rules:

{% stepper %}
{% step %}
The proxy must query the Didomi URL in HTTPS for all files from `https://dsdk.client.com` to `https://sdk.privacy-center.org` with their associated path, method, headers, and body.

{% hint style="info" %}
For instance, the request `GET https://dsdk.client.com/loader.js?domain=...` should be proxied to `GET https://sdk.privacy-center.org/loader.js?domain=...`
{% endhint %}
{% endstep %}

{% step %}
The proxy must query the Didomi URL in HTTPS for all requests to `https://dsdk.client.com/api/` to `https://api.privacy-center.org` with their associated path, method, headers, and body.

{% hint style="info" %}
For instance, the request `POST https://dsdk.client.com/api/events` should be proxied to `POST https://api.privacy-center.org/events`.
{% endhint %}
{% endstep %}
{% endstepper %}

#### Add end-user country and region

In addition to the above rules, your organization will need to add the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country and [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) region code to your notice configuration on page load to ensure that the correct `loader.js` file is downloaded from our services to be cached by your proxy correctly.

Add the user country and region directly to your local SDK config object during page load, dynamically setting the `window.didomiConfig.user.country` and `window.didomiConfig.user.region` properties to have their values equal to a valid country and region codes. These settings will override the default geolocation behavior on the `loader.js` route.

```javascript
window.didomiConfig = {
    user: {
        country: "US",
        region: "CA"
    }
}
```

In the example above, an end-user located in California, USA who loads the SDK will end up making a request to the Didomi CDN with `country=US` and `region=CA` parameters at load time.

**Example**

{% code overflow="wrap" %}

```
https://dsdk.client.com/{public API key}/loader.js?target_type=notice&target=4QS9p3Qn&country=US&region=CA
```

{% endcode %}

The request will be proxied to: `https://sdk.privacy-center.org/{public API key}/loader.js?target_type=notice&target=4QS9p3Qn&country=US&region=CA`

{% hint style="info" %}
[Click here](https://developers.didomi.io/cmp/web-sdk/consent-notice/notice/behavior#configuration-by-user-country) for more information on leveraging the `didomiConfig` object for controlling the behavior of an end-user's location. Please note that this may require obtaining a new embed code for your notice and updating the embed code in your HTML if your consent notice was created earlier than September 2023.
{% endhint %}
{% endtab %}
{% endtabs %}

Regardless of whether your organization configures a reverse proxy for its main domain or a dedicated subdomain, the following implementation steps must also be configured:

* [Requests to origin (Didomi CDN)](#requests-to-origin-didomi-cdn)
* [Caching](#caching)
* [Limits](#limits)

#### Requests to origin (Didomi CDN)

When proxying a request to the Didomi CDN, your proxy should be configured with the following rules:

{% hint style="danger" %}
Your proxy **must NOT** query the Didomi CDN more often than indicated by the cache headers returned by the Didomi CDN. In particular, it must not query the Didomi CDN for every single request coming from end-users. Country and region-based caching **MUST** be configured in your proxy.

Your proxy will be **automatically throttled and disabled without warning** if it is querying the Didomi CDN too often.
{% endhint %}

<table><thead><tr><th width="289">Rule</th><th>Description</th></tr></thead><tbody><tr><td>Forward and cache based on path and query string</td><td>The full path and query string of requests sent to <code>sdk.privacy-center.org</code> must be forwarded in its entirety to the Didomi CDN. Caching must be done on the full path and query string.<br><br>Requests to <code>api.privacy-center.org</code> must never be cached.</td></tr><tr><td>Cache based on geo (ISO country and region)</td><td><p>The Didomi CDN files are generated and served based on the end-user's ISO country and region codes (determined from the end-user's IP).<br><br>Ensure that your proxy acts the same way and caches different versions of a given file based on the country and region of the user request.</p><p>Files returned by the Didomi CDN are not specific to a given end-user but to the end-user's country and region.</p><p>Requests to <code>api.privacy-center.org</code> must never be cached.</p></td></tr><tr><td>Do not forward cookies</td><td>Cookies should not be forwarded to the Didomi CDN and can be discarded from the request.</td></tr><tr><td>Forward end-user IP</td><td>The original IP of the end-user should be forwarded to the Didomi CDN in the <code>X-Forwarded-For</code> header.</td></tr></tbody></table>

#### Caching

The proxy your organization configures must cache files based on:

* The full path and query string
* The end-user country and region ISO codes

If the reverse proxy does not correctly cache files based on the rules listed above it can be the case that the wrong consent notice could be returned and shown to the end-user (e.g., a GDPR consent notice could be shown to a California end-user even if you have configured CPRA for your consent notice).

**Responses from origin (Didomi CDN) and caching headers**

After receiving a file from the Didomi CDN, your proxy must respect all cache headers returned by the Didomi CDN (Cache-Control, Expires, etc.) to ensure that files updated on the Didomi CDN get updated in your proxy as well.

Your organization must return the cache headers to the end-user as well to limit the number of requests sent by end-users to your proxy and the number of requests sent by your proxy to the Didomi CDN.

If your proxy is querying the Didomi CDN more often than indicated by the cache headers, it must include HTTP headers like `If-Modified-Since` or `Etag` from the cached files.

Files can be cached locally by your proxy and returned if stale to increase reliability.

#### Limits

The following limits apply when using a reverse proxy to serve the Didomi SDK. When your organization publishes changes to a consent notice with the default SDK domain, the consent notice is instantaneously updated on your website. The cache of the Didomi CDN is invalidated to ensure that the changes are immediate. With a reverse proxy, an additional delay is added as the cache of the proxy is not immediately cleared. Having a mechanism to clear the proxy cache after publishing a consent notice can help resolve this problem.

## Implementation guides

For your organization's convenience, Didomi has compiled dedicated resources for implementing reverse proxy for the following platforms:

* [AWS CloudFront](/api-and-platform/domains/reverse-proxy/implementation-guides/aws-cloudfront.md)
* [Cloudflare](/api-and-platform/domains/reverse-proxy/implementation-guides/cloudflare.md)
* [Fastly](/api-and-platform/domains/reverse-proxy/implementation-guides/fastly.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.didomi.io/api-and-platform/domains/reverse-proxy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.