Multiple Custom Domains

Learn how to configure and manage multiple custom domains within a single Auth0 tenant for multi-brand and multi-region deployments.

Within Auth0, a custom domain allows you to unify the login experience with your own brand and products. Multiple Custom Domains enables you to configure multiple custom domains within a single Auth0 tenant. This feature is available for Enterprise customers on both Public Cloud and Private Cloud deployments.

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 provides a base entitlement of up to 20 custom domains per tenant.
• Additional custom domains beyond the base entitlement are available through an add-on SKU. Please reach out to Auth0 sales for details.
• You must be able to prove ownership of the configured custom domains.

Configure Multiple Custom Domains

You can add and manage multiple custom domains for your tenant using either the Auth0 Dashboard or the Management API.

Auth0 Dashboard

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:

   • Domain: A fully-qualified domain name that you own. For example: my.custom-domain.com.
   • Certificate type: Choose Auth0-managed certificates or Self-managed certificates.
   • Metadata (Key/Value): Add optional metadata like region, client_name, or client_id, to help organize and filter your domains.

4. Once you have configured the custom domain details, select Save.

Your newly added domain name will show as pending until verification is complete.

View and manage domains

The Custom Domains page displays all configured domains. You can:

• Search: Find domains by name using the search box
• Filter: Filter domains by verification status, certificate type, or metadata values
• Sort: Sort domains by name, creation date, or verification status
• View details: Click on any domain to see detailed configuration, verification status, and certificate information
• Set default: Designate a domain as the default domain for your tenant

These features help you efficiently manage large numbers of custom domains across your tenant.

Management API

To create a custom domain with the Management API, you need a machine-to-machine (M2M) application that is authorized to use the Management API. For more information, review Management API Access Tokens.

1. Navigate to Dashboard > Applications > Applications and select Create Application.

2. Enter a descriptive name for your application and choose Machine to Machine Applications. Then, select Create.

3. Switch to the APIs view and then enable toggle for the Auth0 Management API.

4. Expand the row to configure API’s permissions. For MCD, you must select the following:

   • read:custom_domains
   • create:custom_domains
   • update:custom_domains
   • delete:custom_domains

5. Select Update.

6. Navigate to the Settings tab to gather your Client ID, Client Secret, and Domain.

7. Review Get Management API Access Tokens to retrieve and store your access token.

Create a Custom Domain

You can create a new custom domain by sending a POST request to the /api/v2/custom-domains endpoint. See the example below to create a new custom domain using the Management API explorer, using the credentials retrieved above:

If successful, you should see the following returned with the details of your new custom domain, including it’s verification status. The status is initially returned as pending.

{
    "custom_domain_id": "cd_abc123def456",
    "domain": "your.example-custom-domain.com",
    "primary": false,
    "status": "pending",
    "type": "auth0_managed_certs",
    "verification": {
        "methods": [
            {
                "name": "CNAME",
                "record": "yourtenant.auth0.com",
                "domain": "your.example-custom-domain.com"
            }
        ]
    },
    "tls_policy": "recommended",
    "domain_metadata": {
        "environment": "development"
    }
}

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 is supported by the following Auth0 Management SDKs: Node.js, Go, Python, Java, and .NET. Authentication SDKs automatically work with custom domains when configured in your application.

Default domain

When multiple custom domains are configured, you can designate a domain as the default domain. The default domain is used when domain info is required for Auth0 Management API endpoints but the custom domain is not explicitly specified via auth0-custom-domain header. This info is used to customize email notifications (e.g. password resets and email verification) with domain specifics.

To set a default domain:

1. Navigate to Auth0 Dashboard > Branding > Custom Domains
2. Find the domain you want to set as default in the list
3. Click the Set as Default button for that domain

You can also set the default domain using the Management API by updating a custom domain’s configuration. Once set, the default domain will be automatically used for customizing email communications unless a specific domain is provided via the auth0-custom-domain header.

The default domain makes the auth0-custom-domain header optional for Management API endpoints that trigger notifications. If you don’t specify a custom domain when calling these endpoints, Auth0 will automatically use the default domain for email customizations.

Domain verification

The method for verifying domain name ownership depends on your chosen management type:

Domain Type	Verification Method	Details
Auth0-Managed	CNAME DNS record	Configure this record to confirm domain ownership and activate your domain.
Self-Managed	TXT DNS record	Specific 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, Universal Login, 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 [e-mail]. 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 following Management API endpoints accept the auth0-custom-domain HTTP header:

• Send an email address verification email
• Create an email verification ticket
• Create invitations to an organization
• Create a user
• Create a multi-factor authentication enrollment ticket
• Create a password change ticket
• Update a user

For example: To create a password change ticket using Auth0 SDK for Node.js.

import { ManagementClient, CustomDomainHeader } from "auth0";

// Client-level: auto-applies to whitelisted endpoints
const auth0 = new ManagementClient({
    domain: '{yourDomain}',
    clientId: '{yourClientId}',
    clientSecret: '{yourClientSecret}',
    withCustomDomainHeader: '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);
    }
})();

// Alternatively, use per-request override
const reqOptions = {
    ...CustomDomainHeader('my-custom-domain.com'),
};
const ticket = await auth0.tickets.changePassword(
    { user_id: 'auth0|abc123', result_url: 'https://example.com/success' },
    reqOptions
);

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 code	Message
409	The tenant has multiple verified custom domains.
400	The custom domain does not exist for the tenant.
400	The 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 execute using your default custom domain rather than the standard Auth0 domain.

Application URL placeholders

You can use custom domain metadata as dynamic placeholders in application URLs such as callback URLs, logout URLs, and the Application Login URI (initiate_login_uri). This allows each custom domain to resolve to a different application URL at runtime. To learn more, read Custom domain URL placeholders.

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.custom_domain, which provides the custom domain 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.custom_domain?.domain property
2. Compares that domain with both lists
3. Allows or denies the user access accordingly

exports.onExecutePostLogin = async (event, api) => {
    const customDomain = event?.custom_domain?.domain;
    
    console.log(`org ${event?.organization?.name} accessed from domain ${customDomain || 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(customDomain) : false);
        
    if (isDomainDenied()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${customDomain}`);
    }

    // (B) checks org's allow_list
    const isDomainAllowed = () =>
        (event?.organization?.metadata?.allow_domains ? event?.organization?.metadata?.allow_domains.split(',').map(d => d.trim()).includes(customDomain) : false);
        
    if (!isDomainAllowed()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${customDomain}`);
    }
};

MCD provides access to custom domain metadata in Actions through the event.custom_domain object. You can use this information along with the custom domain metadata configured in your tenant to implement domain-specific logic in your Actions.

Custom domain attributes

MCD provides the following attributes related to custom domain verification and SSL/TLS certificate management. These attributes provide granular insights into the provisioning and operational status of custom domains.

Updated attributes

Attribute	Description
status	A 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:

Attribute	Description
verification.status	Status of the DNS record verification process. Possible values are: verified, pending, and failed.
verification.error_msg	In 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_at	This 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.
certificate	This object encapsulates information related to the SSL/TLS certificate associated with the custom domain.
certificate.status	This 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_msg	If 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_authority	This string attribute specifies the Certificate Authority that issued the SSL/TLS certificate for the custom domain.
certificate.renews_before	For 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.

Limitations

The following limitations apply to Multiple Custom Domains:

• WebAuthn/Passkeys:
  • Each custom domain maintains its own passkey enrollment. A passkey enrolled on one custom domain is tied to that specific Relying Party ID (RP ID) and cannot be used across other domains.
  • If a user enrolled a roaming security key under Domain A and attempts to log in via Domain B, the authentication will not simply fail. Instead, because the RP IDs do not match, the system will immediately present the user with a new enrollment screen.