Multiple Custom Domains (MCD) support in a single tenant is currently available in Early Access (EA). This capability is available only for Enterprise customers. If you are interested in using this feature, please reach out to your Sales exec/Technical Account Manager or open a support ticket through the Auth0 Support Center.To learn more about Auth0’s product release cycle, review Product Release Stages.
Within Auth0, a allows you to unify the login experience with your own brand and products. Multiple custom domains EA capability enables you to configure up to 1000 custom domains within a single Auth0 tenant. Please see the prerequisites below, including the applicable limits and conditions at General Availability (GA).

​
Prerequisites

Before getting started with MCD, review the requirements below:
  • Your tenant is on an Enterprise plan (Public Cloud or Private Cloud deployments). For more information, see Manage Subscriptions.
  • Your Enterprise plan will provide a base entitlement of up to 20 custom domains per tenant in the MCD General Availability (GA) release.
  • EA allows up to 1,000 custom domains per tenant for experimentation and validation. Once MCD GA launches, the base entitlement of up to 20 custom domains will apply. Any domains beyond the base entitlement will require an additional add-on SKU.
  • You must be able to prove ownership of the configured custom domains.

​
Configure Multiple Custom Domains

Auth0 will enable the MCD feature on tenants requested by EA participants. You can then add MCD to a tenant with the or in the .
To create a custom domain in the Auth0 Dashboard:
  1. Navigate to Auth0 Dashboard > Branding > Custom Domains.
  2. Select +Add custom domain.
  3. In the configuration form, provide the following information:
  4. Once you have configured the custom domain details, select Save.
Your newly added domain name will show as pending until verification is complete.

​
MCD features

MCD offers many key features and functionalities to more effectively manage your Auth0 implementation and improve user experience. You are responsible for owning and registering your desired custom domains with a domain name registrar. The Auth0 Management API provides comprehensive support for Create, Read, Update, Delete, and Verify operations for these custom domains, offering full programmatic control over their lifecycle. MCD EA supports the following Auth0 SDKs: Node.js and Go.

​
Domain verification

The method for verifying domain name ownership depends on your chosen management type:
Domain TypeVerification MethodDetails
Auth0-ManagedCNAME DNS recordConfigure this record to confirm domain ownership and activate your domain.
Self-ManagedTXT DNS recordSpecific TXT record details are provided in the Create API response.
After your custom domain has been verified by Auth0, you can use it immediately to configure Auth0 features for your users. For more information, read Configure Features to Use Custom Domains.

​
Metadata for enhanced management

You can provision up to 10 metadata fields per custom domain for easier organization and future customization. In upcoming releases, these metadata fields will enable advanced customization of email templates, , and authentication logic.

​
Customize email templates

Leverage your custom domain information to personalize and brand your email templates, ensuring a consistent user experience.  To facilitate this, MCD provides the custom_domain.domain variable for use in Liquid Syntax. For example, you could set the From Address of your email template to support@{{ custom_domain.domain }} , which would render as support@my.custom-domain.com. This variable is available through Liquid Syntax in the From Address, Subject, and Message fields. To learn more, read Customize Email Templates.

​
Customize email handling using the Management API

If you configured Multiple Custom Domains and enabled Use Custom Domains in Emails, the auth0-custom-domain HTTP header is available when using the Auth0 Management API. The header is passed as the value for the domain object in email templates.
The auth0-custom-domain HTTP header is required if MCD is configured with at least 1 domain in ready state. If you are moving from a single custom domain to MCD, you must update your existing Management API email requests to include the auth0-custom-domain HTTP header .
The following Management API endpoints accept the auth0-custom-domain HTTP header: For example: To create a password change ticket using Auth0 SDK for Node.js. 
const { ManagementClient } = require('auth0');

const auth0 = new ManagementClient({
    domain: '<YOUR_AUTH0_DOMAIN>',
    clientId: '<YOUR_CLIENT_ID>',
    clientSecret: '<YOUR_CLIENT_SECRET>',
    scope: 'create:passwords_tickets',
    headers: {
        'auth0-custom-domain': 'my-custom-domain.com'
    }
});

(async () => {
    try {
        const ticket = await auth0.tickets.changePassword({
            user_id: 'auth0|abc123',
            result_url: 'https://example.com/success'
        });
        console.log('Password change ticket created:', ticket.data.ticket);
    } catch (err) {
        console.error('Error creating password change ticket:', err);
    }
})();
Sample response: The custom domain is passed in the header used to generate the ticket URL. 
{
    "ticket": "https://my-custom-domain.com/u/reset-verify?ticket=abc123"
}
Response messages
When you provide the auth0-custom-domain HTTP header, the following additional response types are possible:
HTTP status codeMessage
409The tenant has multiple verified custom domains.
400The custom domain does not exist for the tenant.
400The auth0-custom-domain HTTP header has an invalid format.
If you enable MCD and use the Auth0 Dashboard to configure Email templates, the Try feature will not allow you to test with a custom domain.

​
Multiple Custom Domains with Actions

Auth0 Actions allows you to create custom logic handling of your different transactions based on the custom domain. For example, you could create an Action that directs a user to an associated Organization, or enforce a specific access control policy. To facilitate this, post-login Actions features the object event.request.hostname, which provides the hostname being used for the authentication flow.

​
Use case: Restrict user access to an Organization based on custom domain

Store a domain allowlist and denylist (for example, allow_domains and deny_domains) in your Organization’s metadata. Create an Action that:
  1. Gets the user’s domain through the event.request.hostname property
  2. Compares that domain with both lists
  3. Allows or denies the user access accordingly
exports.onExecutePostLogin = async (event, api) => {

    console.log(`org ${event?.organization?.name} accessed from domain ${event?.request?.hostname}`);

    if (event?.organization?.metadata?.deny_domains && event?.organization?.metadata?.allow_domains) {
        console.warn(`[WARNING] configuration issue. org ${event?.organization?.name} has both deny_domains and allow_domains`);
    }

    // Check either deny (A) allow (B) not both

    // (A) checks org's deny_list
    const isDomainDenied = () =>
        (event?.organization?.metadata?.deny_domains ? event?.organization?.metadata?.deny_domains.split(',').map(d => d.trim()).includes(event?.request?.hostname) : false);

    if (isDomainDenied()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${event?.request?.hostname}`);
    }

    // (B) checks org's allow_list
    const isDomainAllowed = () =>
        (event?.organization?.metadata?.allow_domains ? event?.organization?.metadata?.allow_domains.split(',').map(d => d.trim()).includes(event?.request?.hostname) : false);

    if (!isDomainAllowed()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${event?.request?.hostname}`);
    }

};
MCD GA will introduce a new custom domain Action object, which will include custom domain metadata. Your Action code will need to be updated at GA if you use the new object.

​
Custom domain attributes

The MCD EA release introduces the following attributes related to custom domain verification and SSL/TLS certificate management. These additions provide granular insights into the provisioning and operational status of custom domains. Please be aware that the attributes and their descriptions outlined in this document are subject to change in future releases.

​
Updated attributes

AttributeDescription
statusA new enumeration value, failed, has been added to the status attribute. This value indicates that the custom domain verification process has encountered an error and was unsuccessful. This is in addition to the existing supported values pending and ready.

​
New attributes

The following attributes are supported for Auth0-managed domains only:
AttributeDescription
verification.statusStatus of the DNS record verification process. Possible values are: verified, pending, and failed.
verification.error_msgIn the event that verification.status indicates a failure, this string attribute will contain a human-readable error message providing context for the verification failure.
verification.last_verified_atThis timestamp attribute records the date and time of the last successful verification of the custom domain. The format of this timestamp will adhere to ISO 8601.
certificateThis object encapsulates information related to the SSL/TLS certificate associated with the custom domain.
certificate.statusThis attribute indicates the current provisioning status of the SSL/TLS certificate. Possible values will include states such as provisioning, provisioned, provisioning_failed, and renewing_failed.
certificate.error_msgIf the certificate.status is provisioning_failed or renewing_failed, this string attribute will provide a user-friendly error message detailing the reason for the failure.
certificate.certificate_authorityThis string attribute specifies the Certificate Authority that issued the SSL/TLS certificate for the custom domain.
certificate.renews_beforeFor Auth0-managed custom domains, this new timestamp attribute indicates the date and time before which the SSL/TLS certificate must be renewed. The format of this timestamp will adhere to ISO 8601.