> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-actions-triggers-prototype.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Best practices for implementing and managing multiple custom domains in Auth0.

# Multiple Custom Domains Best Practices

Implementing [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains) (MCD) effectively requires thoughtful planning and adherence to best practices. By following these guidelines, you can ensure scalability, maintain robust security, and deliver a consistent brand experience across all your custom domains.

This guide covers best practices for planning, security, performance, operations, and user experience when using multiple custom domains.

## Verify ownership of domains

Make sure you are ready to verify ownership of your custom domains in a timely manner. Leaving domains unverified for too long can clutter your space and complicate the management process.

## Planning and architecture

### Choose a domain strategy

Before implementing MCD, decide on your domain strategy:

* **By brand**: Separate custom domains for each brand (e.g., `login.brand1.com`, `login.brand2.com`)
* **By region**: Regional domains for compliance or performance (e.g., `login.us.example.com`, `login.eu.example.com`)
* **By customer**: Dedicated domains for enterprise customers (e.g., `login.customer1.com`, `login.customer2.com`)
* **Hybrid**: Combination of strategies (e.g., brand + region: `login-us.brand1.com`)

### Configure a default domain

Always configure a [default custom domain](/docs/customize/custom-domains/multiple-custom-domains/default-domain) to:

* Simplify configuration for applications that don't need domain-specific behavior
* Provide fallback for email notifications
* Reduce the need for explicit domain specification in API calls

**Best practice**: Use a generic or administrative domain as default (e.g., `login.company.com` or `admin.company.com`) rather than a brand-specific domain.

### Plan for scale

Consider future growth when designing your MCD architecture:

* **Document domain assignments**: Maintain clear documentation of which applications use which domains
* **Reserve domain patterns**: Register domains you may need in the future
* **Monitor limits**: Track your domain count against entitlement limits
* **Plan for expansion**: Design your architecture to accommodate additional domains

## Use metadata to stay organized

Leverage the metadata fields available for each custom domain to enable efficient management and customization:

**Recommended metadata fields**:

* `brand`: Brand identifier (e.g., "BrandA", "BrandB")
* `region`: Geographic region (e.g., "us-east", "eu-west")
* `environment`: Environment type (e.g., "production", "staging")
* `customer_id`: Customer or tenant identifier
* `support_email`: Domain-specific support contact
* `purpose`: Domain purpose (e.g., "customer-portal", "admin-portal")

**Example metadata structure**:

```json theme={null}
{
  "brand": "BrandA",
  "region": "us-east",
  "environment": "production",
  "customer_id": "cust_12345",
  "support_email": "support@brand-a.com",
  "tier": "enterprise"
}
```

Use metadata for:

* **Email customization**: Personalize email templates based on metadata
* **Actions logic**: Implement domain-specific authentication rules
* **Filtering and search**: Organize domains in your management tooling
* **Reporting**: Track usage and performance by brand, region, or customer

## Security

When implementing multiple custom domains, consider these security patterns based on your use case:

* **Domain validation**: Prevent unauthorized domain usage by restricting authentication to specific custom domains
* **Organization isolation**: Ensure users can only access organizations through approved domains
* **Certificate management**: Maintain secure certificate lifecycle management

### Domain validation in Actions

Use [Actions](/docs/customize/actions) to restrict authentication to specific custom domains. This is useful when you want to prevent users from authenticating via the canonical Auth0 domain or restrict access to specific brand domains:

```javascript theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const domain = event.custom_domain?.domain;

  // List of allowed custom domains
  const allowedDomains = [
    'login.brand1.com',
    'login.brand2.com',
    'login.example.com'
  ];

  if (!domain || !allowedDomains.includes(domain)) {
    return api.access.deny(
      `Authentication from ${domain} is not permitted.`
    );
  }
};
```

### Organization-based access control

If you use [Auth0 Organizations](/docs/manage-users/organizations), you can restrict which custom domains are allowed for each organization. This is useful in B2B scenarios where each customer has their own branded domain and should only access their organization through that domain:

```javascript theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const domain = event.custom_domain?.domain;

  if (!event.organization) {
    return;
  }

  // Check organization's allowed domains
  const allowedDomains = event.organization.metadata?.allowed_domains?.split(',') || [];

  if (allowedDomains.length > 0 && !allowedDomains.includes(domain)) {
    return api.access.deny(
      `Access to ${event.organization.name} requires authentication via an approved domain.`
    );
  }
};
```

### Certificate management

* **Monitor expiration**: Set up alerts for certificate expiration dates
* **Automate renewal**: Use Auth0-managed certificates for automatic renewal
* **Document self-managed processes**: If using self-managed certificates, maintain clear runbooks

## Performance

### Use regional domains

For global applications, consider using region-specific custom domains to help with data residency requirements and branding by region:

* Examples: `login-us.example.com`, `login-eu.example.com`, `login-ap.example.com`

<Note>
  Authentication latency depends on where your Auth0 tenant is deployed, not on the custom domain name. Choose your tenant's region based on where your users are located.
</Note>

## Branding and user experience

### Keep branding consistent

MCD adds another dimension to your branding efforts. Users expect consistency across all touchpoints:

* **Universal Login**: Customize login pages per domain using domain metadata
* **Email templates**: Use custom domain variables to personalize emails
* **Application UI**: Match your application's branding with the authentication experience

For comprehensive guidance, refer to [B2B](/docs/get-started/architecture-scenarios/business-to-business/branding) and [B2C](/docs/get-started/architecture-scenarios/business-to-consumer/branding) branding guidelines.

### Passkey management

* **Communicate clearly**: Inform users that passkeys are per-domain
* **Prompt enrollment**: Encourage passkey enrollment after the 3rd login
* **Track enrollment**: Monitor which domains users have enrolled passkeys for
* **Provide help**: Offer clear documentation about passkey management

See [Passkeys with Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains/passkeys) for detailed guidance.

### User communication

When users interact with multiple custom domains:

* **Set expectations**: Explain that different brands/portals may have different login URLs
* **Provide guidance**: Help users understand which domain to use
* **Handle errors gracefully**: Display clear error messages if users try to access the wrong domain
* **Support documentation**: Maintain clear docs about your domain structure

## Operations and maintenance

### Monitoring and alerting

Set up monitoring for:

* **Certificate expiration**: Alert 30, 15, and 7 days before expiration
* **Domain verification status**: Monitor for verification failures
* **Authentication failures**: Track failures by custom domain
* **DNS health**: Monitor DNS resolution for all custom domains
* **API performance**: Track Management API latency for domain operations

### Documentation

Maintain comprehensive documentation:

* **Domain inventory**: List of all custom domains with metadata and purpose
* **Application mappings**: Which applications use which domains
* **Runbooks**: Procedures for common operations (adding domains, certificate renewal, troubleshooting)
* **Architecture diagrams**: Visual representation of domain structure
* **Contact information**: Responsible teams/individuals for each domain

### Testing

Test thoroughly before production:

* **Functional testing**: Verify authentication for each custom domain
* **Integration testing**: Test all applications with their assigned custom domains
* **Email testing**: Verify emails use correct custom domains
* **Failover testing**: Test fallback to default domain
* **Performance testing**: Load test authentication through custom domains

### Change management

When making changes to custom domains:

* **Use staging first**: Test changes in non-production environments
* **Gradual rollout**: Roll out changes to a subset of domains first
* **Monitor closely**: Watch for issues during rollout
* **Have rollback plan**: Be prepared to revert changes if needed
* **Communicate changes**: Notify stakeholders of planned changes

## Common pitfalls to avoid

### Don't over-complicate domain structure

* **Anti-pattern**: Creating a custom domain for every possible variation
* **Better approach**: Start with a few core domains and expand as needed

### Don't forget to update all integration points

When adding new custom domains, update:

* Application callback URLs
* Social provider redirect URIs
* Enterprise connection endpoints
* Token validation logic
* Monitoring and alerting rules

### Don't neglect documentation

* **Anti-pattern**: Relying on institutional knowledge
* **Better approach**: Document domain assignments, metadata meanings, and operational procedures

### Don't ignore certificate management

* **Anti-pattern**: Letting certificates expire without warning
* **Better approach**: Automate monitoring and renewal processes

### Don't mix authentication contexts

* **Anti-pattern**: Using the same custom domain for unrelated brands/customers
* **Better approach**: Maintain clear separation between different authentication contexts

## Learn more

* [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains)
* [Default Custom Domain](/docs/customize/custom-domains/multiple-custom-domains/default-domain)
* [Management API for Multiple Custom Domains](https://auth0.com/docs/api/management/v2)
* [Migration Guide](/docs/customize/custom-domains/multiple-custom-domains/migration-guide)
* [Actions Integration](/docs/customize/custom-domains/multiple-custom-domains/actions-integration)
* [Passkeys with Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains/passkeys)