Skip to main content
When you have multiple custom domains configured for your Auth0 tenant, you can designate one as the default custom domain. The default domain simplifies configuration and ensures a consistent user experience when a custom domain is not explicitly specified.

​
What is a default custom domain?

The default custom domain is the custom domain that Auth0 uses automatically when:
  • Email and phone communications: Sending password reset emails, email verification links, and other Auth0-generated notifications when no specific custom domain is specified. This includes scenarios where notifications are sent as part of authentication flows.
  • Management API calls: Handling API requests that trigger notifications without the auth0-custom-domain header
You can configure your canonical tenant domain (YOUR_TENANT.auth0.com or YOUR_TENANT.REGION.auth0.com) as the default custom domain. There will always be a default custom domain configured for your tenant.

​
Benefits of setting a default domain

Setting a default custom domain provides several advantages:
  • Simplified configuration: Reduces the need to specify custom domains in every Management API call or configuration
  • Consistent branding: Ensures users always see your brand, even when a specific domain isn’t specified
  • Optional auth0-custom-domain header: Makes the custom domain header optional in Management API requests
  • Fallback behavior: Provides sensible defaults for multi-brand or multi-tenant implementations
  • Easier migration: Simplifies transitioning from a single custom domain to multiple custom domains

​
Configure a default domain

You can set a default custom domain through the Auth0 Dashboard or the Management API.

​
Using the Auth0 Dashboard

To set a default custom domain in the Auth0 Dashboard:
  1. Navigate to Auth0 Dashboard > Branding > Custom Domains
  2. Find the verified custom domain you want to set as default in the list
  3. Click the Set as Default button for that domain
  4. Confirm the action in the dialog that appears
The domain will now show a “Default” badge in the custom domains list.
Only verified custom domains can be set as the default. Ensure your custom domain is fully verified and active before designating it as the default.

​
Using the Management API

To set a default custom domain via the Management API, use the PATCH /api/v2/custom-domains/default endpoint:

​
Remove default domain designation

To remove the default designation from a custom domain:
  1. Set a different custom domain as the default (only one domain can be default at a time), or
  2. Use the Management API to set is_default: false on the current default domain
When no custom domain is set as default, Auth0 will use your canonical tenant domain.

​
How the default domain is used

​
Email notifications

When Auth0 sends email notifications (password resets, email verification, welcome emails), the default domain’s context is available in email templates. You can customize email templates to use custom domain information in the “From” address, subject line, and email body. To enable custom domain usage in emails:
  1. Navigate to Auth0 Dashboard > Branding > Custom Domains
  2. Enable the Use Custom Domain in Emails toggle
  3. Customize your email templates as desired to use the custom domain information

​
Management API calls

When making Management API calls, the auth0-custom-domain header becomes optional if you have a default domain configured: If you don’t provide the auth0-custom-domain header and a default domain is configured, Auth0 will automatically use the default domain for the operation.

​
Using the default domain with Actions

Use Actions to implement logic based on the custom domain: 
exports.onExecutePostLogin = async (event, api) => {
  const domain = event.custom_domain?.domain;

  // Store the login domain in user metadata
  if (domain) {
    api.user.setAppMetadata('login_domain', domain);
  }
};
To learn more about using custom domain information in Actions, see Actions Integration with Multiple Custom Domains.

​
Best practices

When configuring a default custom domain, consider these best practices:
  • Choose a stable domain: Select a domain that won’t change frequently as your default
  • Verify before setting: Ensure the domain is fully verified and operational before making it default
  • Document the decision: Record why a particular domain was chosen as default for future reference
  • Test email flows: After setting a default domain, test password reset and email verification flows
  • Monitor token issuers: Verify that tokens have the expected iss claim after setting a default
  • Plan for multi-brand scenarios: If you serve multiple brands, choose a generic or admin domain as default
  • Update integrations: Inform your team about the default domain to ensure proper integration configuration

​
Learn more