Multiple Custom Domains

​

Prerequisites

• 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

{
    "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

​

Default domain

• Sending email notifications (password resets, email verification, etc.) and the custom domain is not explicitly specified
• Making API calls to Auth0 endpoints without specifying a custom domain
• The auth0-custom-domain header is not provided in Management API requests

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

​

Domain verification

​

Metadata for enhanced management

​

Customize email templates

​

Customize email handling using the Management API

• 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

const { ManagementClient } = require('auth0');

const auth0 = new ManagementClient({
    domain: '{yourDomain}',
    clientId: '{yourClientId}',
    clientSecret: '{yourClientSecret}',
    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);
    }
})();

{
    "ticket": "https://my-custom-domain.com/u/reset-verify?ticket=abc123"
}

Response messages

​

Multiple Custom Domains with Actions

​

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

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) => {
    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}`);
    }
};

​

Custom domain attributes

​

Updated attributes

​

New attributes

​

Limitations

• WebAuthn/Passkeys: Each custom domain can have its own passkey enrollment. Users will need to enroll passkeys separately for each custom domain they authenticate through. Related origins support for shared passkey credentials across domains is planned for a future release.