# Domain delegation

Delegated domains are used in Didomi to:

* load the SDK and send API requests
* load webpage

You delegate a domain that is fully managed by Didomi. All traffic to that domain will be routed directly to Didomi's infrastructure.

> You can create domains to load the SDK of your consent notice when your user lands on your website or your single purpose widget to collect preferences about the user to improve his experience.
>
> Using first-party domains reduces reliance on browsers and helps you better capture visitor consent to serve ads that comply with their choices.

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

## Schema

| Property     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`         | Fully qualified domain name (e.g. `cmp.didomi.io`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `usage`      | What the domain is used for: Load a SDK (`cmp`) or Load a webpage (`preference-center`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `type`       | Type of the domain. `custom` indicates a domain owned and delegated by a client while `managed` indicates a domain that Didomi owns and manages like "privacy-center.org". This is automatically set when a domain is created                                                                                                                                                                                                                                                                                                                          |
| `status`     | <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> |
| `bots_crawl` | <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>                                                                                                                                                                                                                                                                                                              |

## Create a domain

### Create the DNS record for your domain

If you have multiple websites and intend to use the domain for sharing consents between websites, we recommend picking a sub-domain of your website that has the most traffic.

{% hint style="danger" %}
Before creating a domain in Didomi, **ensure it is correctly configured and fully propagated in your DNS provider**. Otherwise, domain provisioning will fail.
{% endhint %}

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

<table data-header-hidden><thead><tr><th width="185.84895833333331">Parameter name</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td>Parameter name</td><td>Value</td><td>Notes</td></tr><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>

If you need help with this step, feel free to reach out to <support@didomi.io> and we'll be happy to help.

{% hint style="warning" %}
**If you are using CloudFront from Amazon Web Services**

To support your custom domain, we will create a dedicated CloudFront distribution with your custom domain as a CNAME. Because of AWS restrictions, it is not possible for us 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

You can create a domain by sending a **POST** request to the `/domain` endpoint.

To do so, you must provide:

* `id`: the domain name
* `usage`: the intended usage of the domain
* `organization_id`: the ID of the organization
* `status`: set to `scheduled` to trigger provisioning
* `bots_crawl` : whether bots are allowed to crawl the domain

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

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

{% hint style="success" %}
Once your domain is created and marked as ready, refer to these documentations to use it in your [consent notice](https://developers.didomi.io/cmp/web-sdk/serve-didomi-assets-from-your-domain) or in your [preference/privacy request widgets](https://developers.didomi.io/api-and-platform/widgets/privacy-widgets/deploy-a-widget/use-your-own-domain).
{% endhint %}

#### Retry a failed domain

If domain provisioning fails, the domain status will be set to **failed**. To retry:

1. Ensure the DNS records are correctly configured and fully propagated.
2. [**Delete**](#delete-a-domain) the failed domain.
3. [**Create**](#create-a-domain) the domain again using the same information.

### List the domains

You can list the domains of your organization by sending a GET request to the `/domain` endpoint.

```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
    },
```

{% hint style="info" %}
You can list a specific domain by sending a **GET** request to the `/domains/{id}` endpoint.
{% endhint %}

{% hint style="success" %}
Once your domain is created and marked as ready, refer to these documentations to use it in your [consent notice](https://developers.didomi.io/cmp/web-sdk/serve-didomi-assets-from-your-domain) or in your [preference/privacy request widgets](https://developers.didomi.io/api-and-platform/widgets/privacy-widgets/deploy-a-widget/use-your-own-domain).
{% endhint %}

### Delete a domain

You 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" %}
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"
}
```