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 for:
  • 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 during authentication.
  • 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 is used for links and customizations in these notifications. You can customize email templates to use custom domain information in the “From” address, subject line, and email body.

​
Management API endpoints that trigger notifications

The default custom domain is used specifically for Management API endpoints that trigger email or phone notifications. The auth0-custom-domain header becomes optional for these endpoints when you have a default domain configured. Endpoints that trigger email notifications:
  • POST /api/v2/tickets/password-change - Sends password reset email
  • POST /api/v2/tickets/email-verification - Sends email verification
  • POST /api/v2/jobs/verification-email - Sends verification email to user(s)
  • POST /api/v2/users - Can trigger welcome email if configured
  • PATCH /api/v2/users/{id} - Can trigger verification email when email is updated
Endpoints that trigger phone notifications:
  • POST /api/v2/users/{id}/phone/verification - Sends SMS verification code
Example: When you don’t provide the auth0-custom-domain header for these notification endpoints, Auth0 automatically uses the default custom domain for links and customizations in the email or SMS. You can override this on a per-request basis by including the auth0-custom-domain header.

​
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