> 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/domain-delegation.md).

# Domain delegation

Domain delegation is a method by which your organization can configure a custom domain to serve the Didomi SDKs and API assets through its own domain. Through this method your organization will delegate a domain that is fully managed by Didomi and all traffic to that domain will be routed directly to the Didomi infrastructure. This delegated domain will be used to:

* load the SDK and send API requests
* load webpage

|                        | Load the SDK (cmp) | Load as a webpage (preference-center) |
| ---------------------- | ------------------ | ------------------------------------- |
| Consent notice         | ✅                  | ❌                                     |
| Preference widget      | ✅                  | ✅                                     |
| Privacy request widget | ✅                  | ✅                                     |

In this article, we will cover the following in regards to your organization's domain delegation implementation:

* [Create DNS record for domain](#create-dns-record-for-domain)
* [Create a domain](#create-a-domain)
* [Confirm domain provisioning](#confirm-domain-provisioning)

{% hint style="warning" %}
**Note**: Domain delegation (NS delegation) is also available via the Didomi console. [Click here](https://docs.didomi.io/organization-and-account-settings/domains/create-custom-domain) for more information.
{% endhint %}

***

### Create DNS record for domain

Before your organization creates a domain in Didomi, you will want to ensure that the domain is correctly configured and fully propagated in your DNS provider, as otherwise domain provisioning will fail.

Create a DNS record with your DNS provider or registrar that manages your domain using the following configuration parameters:

{% hint style="info" %}
If your organization has multiple websites and intends to use the domain for sharing end-user consents between websites, Didomi recommends picking a sub-domain of your website that has the most traffic.
{% endhint %}

<table><thead><tr><th width="185.84895833333331">Parameter name</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>Your custom domain (<code>privacy.company-name.com</code> or similar)</td><td>You will be creating a DNS record for a specific sub-domain of your domain name (like privacy., for instance) and not delegating the DNS management of your whole domain.</td></tr><tr><td><strong>Type</strong></td><td>NS (Name server)</td><td>The type NS allows us to generate SSL certificates for the sub-domain and serve your privacy center with SSL/HTTPS.</td></tr><tr><td><strong>TTL (seconds)</strong></td><td>300</td><td></td></tr><tr><td><strong>Value</strong></td><td><p><strong>To load a SDK</strong></p><pre><code>ns1.privacy-center.org
ns2.privacy-center.org
ns3.privacy-center.org
ns4.privacy-center.org
</code></pre><p><br><strong>To load a Webpage</strong></p><pre><code>ns1.preference-center.org
ns2.preference-center.org
ns3.preference-center.org
ns4.preference-center.org
</code></pre></td><td>Didomi's name servers that will host the DNS records for your custom domain</td></tr></tbody></table>

Contact <support@didomi.io> for any assistance your organization may require.

{% hint style="warning" %}
**CloudFront from Amazon Web Services**

In order to support your custom domain, we will create a dedicated CloudFront distribution with your custom domain as a CNAME. Due to AWS restrictions, it is not possible for Didomi to create that distribution if you already have a distribution in your account with either the exact same CNAME or a matching wildcard CNAME.

For instance, if you have chosen to use the custom domain `privacy.company.com` and already have a CloudFront distribution with either `privacy.company.com` or `*.company.com` as CNAMEs, we will not be able to host the custom domain for you.
{% endhint %}

### Create a domain

{% hint style="info" %}
Ensure the domain is configured and fully propagated in your DNS provider before continuing with the instructions below.
{% endhint %}

Create a domain in your organization's Didomi account by sending a **POS**T request to the `/domain` endpoint. In the request body, your organization will need to provide the following:

<table><thead><tr><th width="169">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>Fully qualified domain name (e.g. <code>cmp.didomi.io</code>)</td></tr><tr><td><code>usage</code></td><td>What the domain is used for: Load a SDK (<code>cmp</code>) or Load a webpage (<code>preference-center</code>)</td></tr><tr><td><code>type</code></td><td>Type of the domain. <code>custom</code> indicates a domain owned and delegated by a client while <code>managed</code> indicates a domain that Didomi owns and manages like "privacy-center.org". This is automatically set when a domain is created</td></tr><tr><td><code>status</code></td><td><p>Provisioning status on the Didomi platform.<br><br>Possible values:</p><ul><li><code>draft</code>: domain is created but not deployed yet</li><li><code>scheduled</code>: domain is scheduled for deployment</li><li><code>to_be_deleted</code>: domain is scheduled for deletion</li><li><code>deploying</code>: domain is being provisioned</li><li><code>deleting</code>: domain is being deleted</li><li><code>failed</code>: domain deployment/deletion failed</li><li><code>ready</code>: domain is provisioned and ready for use</li></ul></td></tr><tr><td><code>bots_crawl</code></td><td><p>Controls whether bots are allowed to crawl the domain.<br></p><p>Possible values:</p><ul><li><code>allow_all</code>: allow crawls from any bots (default)</li><li><code>disallow_all</code>: disallow crawls from all bots</li></ul></td></tr><tr><td><code>organization_id</code></td><td>The ID of the organization that owns this data processing</td></tr></tbody></table>

```json
POST https://api.didomi.io/domains

{
  "id": "YOUR_DOMAIN_NAME",
  "usage": "cmp",
  "status": "scheduled",
  "bots_crawl": "allow_all",
  "organization_id": "YOUR_ORGANIZATION_ID"
}
```

### Confirm domain provisioning

View the list of domains for your organization be sending a **GET** request to the `/domain` endpoint and confirm the created domain has a `status` of `ready`.

{% hint style="info" %}
Alternatively, to view the status of the domain directly your organization can send a GET request to the `/domain/{id}` endpoint.
{% endhint %}

```json
GET https://api.didomi.io/domains

RESPONSE

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "YOUR_DOMAIN_NAME",
      "organization_id": "YOUR_ORGANIZATION_ID",
      "description": "My Preference Center",
      "enabled": true,
      "status": "ready",
      "bots_crawl": "allow_all",
      "type": "managed",
      "usage": "preference-center",
      "widget_id": "YOUR_ENTITY_ID", // Deprecated
      "entity_id": "YOUR_ENTITY_ID",
      "error": null,
      "created_at": "2025-06-04T19:23:20.849Z",
      "updated_at": "2025-06-04T19:23:20.849Z",
      "version": 0
    },
```

Review the tabs below for next steps based on the value of the `status` property:

{% tabs %}
{% tab title="ready" %}
Once the domain is created and marked as `ready` your organization can proceed to use the domain when configuring your consent notice and/or preference and privacy request widgets. See the links below for more information:

* [Serve Didomi assets from your own domain (web)](/api-and-platform/domains/serve-didomi-assets-from-your-domain.md)
* [Serve Didomi assets from your own domain (mobile)](/api-and-platform/domains/serve-didomi-assets-from-your-domain-mobile.md)
* [Use custom domain for widget](/api-and-platform/widgets/privacy-widgets/deploy-a-widget/use-your-own-domain.md)
  {% endtab %}

{% tab title="failed" %}
If domain provisioning has failed then the `status` of the domain will be set to `failed`. In order to retry domain provisioning, your organization will need to:

{% stepper %}
{% step %}

#### Check DNS records

Ensure the DNS records are correctly configured and fully propagated
{% endstep %}

{% step %}

#### Delete the failed domain

Your organization can delete a domain by sending a **PATCH** request to the `/domains/{id}` endpoint and setting the status to `to_be_deleted`.

{% hint style="warning" %}
**Note**: If the `entity_id` is not `null` and contains a widget ID, you must first unassign the domain from the widget before you can delete the domain.
{% endhint %}

```json
PATCH https://api.didomi.io/domains/id

{
  "status": "to_be_deleted"
}
```

{% endstep %}

{% step %}

#### Re-create domain

Follow the instructions when [creating a domain](#create-a-domain) using the same information
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}


---

# 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/domain-delegation.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.