Skip to main content
This guide helps you migrate from a single custom domain configuration to multiple custom domains. Whether you’re adding domains for different brands, regions, or customer segments, this guide provides step-by-step instructions for a smooth transition.

​
Migration scenarios

Choose the scenario that best matches your situation:
ScenarioDescriptionUse caseComplexityDowntime
Adding additional domainsYou currently have one custom domain and want to add more while keeping the existing domain operationalExpanding to serve multiple brands or regionsLowNone
Replacing an existing domainYou want to replace your current custom domain with a new oneRebranding or domain ownership changeMediumMinimal (during DNS cutover)
Migrating from canonical domainYou’re currently using your Auth0 canonical domain (e.g., tenant.auth0.com) and want to migrate to custom domainsInitial custom domain implementation with multiple domainsMedium to HighNone (parallel operation)

​
Pre-migration checklist

Before starting your migration, ensure you have completed the following:
  • Verified domain ownership for all new custom domains
  • Reviewed current authentication flows and API integrations
  • Identified all applications using the current domain
  • Documented current email templates and links
  • Obtained SSL/TLS certificates (if using self-managed certificates)
  • Tested the new custom domain configuration in a development or staging environment
  • Prepared rollback plan
  • Scheduled migration during low-traffic period (if applicable)
  • Notified stakeholders and users (if required)

​
Migration steps

​
Add your new custom domains

Add your new custom domains using the Auth0 Dashboard or Management API.

​
Verify domain ownership

Complete the domain verification process for each new custom domain:

​
For Auth0-managed certificates

  1. Note the CNAME record provided by Auth0
  2. Add the CNAME record to your DNS provider
  3. Verify the domain through the Dashboard or API
# Get verification details
curl --request GET \
  --url 'https://{yourDomain}/api/v2/custom-domains/{customDomainId}' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

# Verify after adding DNS record
curl --request POST \
  --url 'https://{yourDomain}/api/v2/custom-domains/{customDomainId}/verify' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

​
For self-managed certificates

  1. Add the required TXT record to your DNS
  2. Configure your reverse proxy or CDN
  3. Upload your SSL certificate
  4. Verify the domain

​
Configure default domain (optional)

If you want one domain to be used by default for emails and API calls, set it as the default domain: 
curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/custom-domains/{customDomainId}' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
  --header 'content-type: application/json' \
  --data '{
    "is_default": true
  }'

​
Update application configurations

Update your applications to use the appropriate custom domain:

​
SDK configuration

Update your Auth0 SDK initialization:

​
Callback URLs

Update your application’s callback URLs in the Auth0 Dashboard:
  1. Navigate to Auth0 Dashboard > Applications. Choose the application to configure and select the Settings tab.
  2. Update Allowed Callback URLs to include the new domain: 
    https://new-domain.example.com/callback
  3. Update Allowed Logout URLs: 
    https://new-domain.example.com/logout
  4. Update Allowed Web Origins: 
    https://new-domain.example.com

​
Update email templates

If you want emails to use your new custom domain:
  1. Navigate to Branding > Custom Domains
  2. Enable Use Custom Domain in Emails
  3. Set your desired domain as the default to make its context available in email templates
  4. Customize your email templates to use the custom domain information in the “From” address, subject, and body as needed
Setting a domain as default makes its context available in email templates, but you must customize your templates to use that information. The default domain’s context will be used when no specific domain is provided through the auth0-custom-domain header.

​
Update social identity providers(IdP)

Update redirect URIs for your social identity providers:

​
Google

  1. Go to Google Cloud Console
  2. Navigate to APIs & Services > Credentials
  3. Add https://new-domain.example.com/login/callback to Authorized redirect URIs

​
Facebook

  1. Go to Facebook Developers
  2. Navigate to your app > Facebook Login > Settings
  3. Add https://new-domain.example.com/login/callback to Valid OAuth Redirect URIs

​
Other providers

Update redirect URIs for all configured social providers following each provider’s documentation.

​
Update enterprise connections (if applicable)

If you use SAML, WS-Fed, Azure AD, or other enterprise connections, update their configuration:

​
SAML connections

Update the Assertion Consumer Service (ACS) URL: 
https://new-domain.example.com/login/callback?connection={connectionName}
You do not need to manually update the ACS URL with your IdP if you use SP-initiated SAML requests and your IdP accepts dynamic ACS.

​
Azure AD connections

  1. Go to Azure Active Directory > App registrations
  2. Select your app > Authentication
  3. Add https://new-domain.example.com/login/callback to Redirect URIs

​
ADFS connections

Update the endpoint in your ADFS settings to use the new custom domain.

​
Test authentication flows

Before completing the migration, thoroughly test:
  1. User login: Verify users can authenticate through the new domain
  2. Password reset: Test password reset emails use the correct domain
  3. Email verification: Verify email verification links work
  4. Social logins: Test each configured social provider
  5. API calls: Verify API calls work with the new domain
  6. Token validation: Ensure JWTs have the correct iss claim

​
Monitor and verify

After migration:
  1. Monitor authentication logs for any errors
  2. Check email delivery and link functionality
  3. Verify SSL certificate validity and expiration dates
  4. Test from different geographic regions (if applicable)
  5. Confirm all applications are using the intended custom domains

​
Decommission old domain (if applicable)

If you’re replacing an existing custom domain:
  1. Ensure all applications have migrated to the new domain
  2. Monitor traffic to the old domain to confirm it’s no longer in use
  3. Consider keeping the old domain active for a grace period
  4. Delete the old custom domain when ready:
curl --request DELETE \
  --url 'https://{yourDomain}/api/v2/custom-domains/{oldCustomDomainId}' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

​
Migration patterns

​
Parallel operation (zero downtime)

Run both old and new custom domains simultaneously:
  1. Add new custom domain
  2. Update new applications to use new domain
  3. Keep existing applications on old domain
  4. Gradually migrate applications
  5. Decommission old domain when fully migrated
Advantages: Zero downtime, gradual rollout, easy rollback Disadvantages: Temporary management overhead

​
Phased migration by application

Migrate applications one at a time:
  1. Identify applications by priority or risk
  2. Migrate low-risk applications first
  3. Monitor for issues before proceeding
  4. Migrate remaining applications
  5. Clean up old configurations
Advantages: Controlled rollout, early issue detection Disadvantages: Longer migration timeline

​
Blue-green deployment

Use separate environments for testing:
  1. Set up new custom domain in staging environment
  2. Test all functionality thoroughly
  3. Cut over production in one operation
  4. Keep old domain as backup
  5. Decommission after verification period
Advantages: Thorough testing, quick rollback Disadvantages: Requires separate environment

​
Handling existing user sessions

When migrating custom domains, existing user sessions may be affected:

​
Session considerations

  • Sessions created with the old domain remain valid until expiration
  • New logins will create sessions with the new domain
  • Cross-domain sessions require careful planning
  1. Notify users: Inform users they may need to log in again
  2. Grace period: Keep old domain active during transition
  3. Session transfer: Use Universal Login to handle session migration
  4. Clear guidance: Provide clear instructions if users experience issues

​
Rollback plan

If you encounter issues during migration:

​
Immediate rollback

  1. Revert application configurations to use the old domain
  2. Keep the new custom domain configured for future attempts
  3. Document the issue for troubleshooting

​
Partial rollback

  1. Identify affected applications
  2. Revert only those applications to the old domain
  3. Investigate and fix issues
  4. Re-migrate when ready

​
Complete rollback

  1. Update all application configurations to use the old domain
  2. If you set a default domain, change it back to the old domain
  3. Notify users of any required actions
  4. Schedule another migration attempt

​
Troubleshooting

​
Common issues and solutions

IssueCauseSolution
Domain verification failsDNS records not propagatedWait for DNS propagation (can take up to 48 hours), verify CNAME record is correct
Login redirects to old domainApplication configuration not updatedUpdate SDK initialization and callback URLs
Email links use wrong domainDefault domain not configuredSet default domain or configure email routing
Social login failsRedirect URIs not updatedAdd new custom domain to social provider’s allowed redirect URIs
Invalid token issuerJWT validation expects old domainUpdate token validation to accept new domain as issuer
SAML assertion errorsACS URL not updatedUpdate SAML configuration with new custom domain URL
Certificate errorsCertificate not provisioned or expiredVerify domain, wait for certificate provisioning, or update certificate

​
Getting help

If you encounter issues during migration:
  1. Check Auth0 Community for similar issues
  2. Review troubleshooting documentation
  3. Contact Auth0 Support with:
    • Your tenant name
    • Custom domain IDs
    • Detailed description of the issue
    • Steps to reproduce
    • Error messages or logs

​
Post-migration best practices

After completing your migration:
  1. Document the configuration: Record which applications use which custom domains
  2. Monitor certificate expiration: Set up alerts for certificate renewal
  3. Review periodically: Ensure custom domain configuration aligns with business needs
  4. Update runbooks: Update operational documentation with new custom domain information
  5. Train team members: Ensure your team understands the new multi-domain setup
  6. Plan for scale: Consider how you’ll manage additional domains in the future

​
Learn more