The Custom Domain does not Exist for the Tenant Error is seen when using Multiple Custom Domains

This article addresses an error that occurs when using the Multiple Custom Domains (MCD) feature. When performing operations related to user management via the Management API, the following error message appears:

The custom domain does not exist for the tenant.

• Custom Domains
• Multiple Custom Domains
• Management API

When using multiple custom domains, a specific header (auth0-custom-domain) is required for certain operations involving user management, as the custom domain in use impacts email templates. This error occurs if the required header is missing or has a value that does not match a verified custom domain on the tenant, when targeting Management API endpoints that support this feature.

For example, if the tenant's canonical domain, https://<TENANT_NAME_AND_REGION>.auth0.com is passed as the value for the auth0-custom-domain header, the error will occur. 

NOTE: This could occur if an Action is triggering the Management API as part of a user login flow, and the Action code is relying upon event.request.hostname to set the domain value, but the login flow was triggered through the canonical domain and thus the event.request.hostname will be the canonical domain.

Ensure that when calling the endpoints mentioned below, the header "auth0-custom-domain" is appended to the request, with a value that equals a custom domain that is verified on the tenant.

Care should be taken if using Actions to trigger the Management API, that the code can reliably set a verified custom domain value for the "auth0-custom-domain" header, and does not send the canonical domain.  (e.g., if using event.request.hostname to dynamically set the header value, all login flows must use a custom domain, and/or the Action's logic should check the canonical domain is not being passed and provide a fallback value for a verified custom domain). Refer to the Customize Email Templates document. 

Currently, the endpoints that support the auth0-custom-domain header include:

• 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

In v5 of the node-auth0 library, the Management Client supports handling the header for the relevant endpoints with the request helper `withCustomDomainHeader`.