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 a domain

• Confirm domain provisioning

Note: Domain delegation (NS delegation) is also available via the Didomi console. Click here for more information.

---

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:

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.

Parameter name	Value	Notes
Name	Your custom domain (privacy.company-name.com or similar)	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.
Type	NS (Name server)	The type NS allows us to generate SSL certificates for the sub-domain and serve your privacy center with SSL/HTTPS.
TTL (seconds)	300
Value	To load a SDK ns1.privacy-center.org ns2.privacy-center.org ns3.privacy-center.org ns4.privacy-center.org To load a Webpage ns1.preference-center.org ns2.preference-center.org ns3.preference-center.org ns4.preference-center.org	Didomi's name servers that will host the DNS records for your custom domain

Contact [e-mail] for any assistance your organization may require.

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.

Create a domain

Ensure the domain is configured and fully propagated in your DNS provider before continuing with the instructions below.

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

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	Provisioning status on the Didomi platform. Possible values: draft: domain is created but not deployed yet scheduled: domain is scheduled for deployment to_be_deleted: domain is scheduled for deletion deploying: domain is being provisioned deleting: domain is being deleted failed: domain deployment/deletion failed ready: domain is provisioned and ready for use
bots_crawl	Controls whether bots are allowed to crawl the domain. Possible values: allow_all: allow crawls from any bots (default) disallow_all: disallow crawls from all bots
organization_id	The ID of the organization that owns this data processing

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.

Alternatively, to view the status of the domain directly your organization can send a GET request to the /domain/{id} endpoint.

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:

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)

• Serve Didomi assets from your own domain (mobile)

• Use custom domain for widget

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:

1

Check DNS records

Ensure the DNS records are correctly configured and fully propagated

2

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.

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.

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

{
  "status": "to_be_deleted"
}

3

Re-create domain

Follow the instructions when creating a domain using the same information