Skip to main content

​
Auth0-managed custom domains

When you configure custom domains with Auth0-managed certificates, there are two custom domain attributes that you can review to query their provision status:
  • verification
  • certificate
You can review the custom domain provision status using Auth0 CLI or the Management API.

​
Auth0 CLI

Use the following command to list the existing domains and their status: 
auth0 domains list
To learn more, read Auth0 CLI documentation.

​
Auth0 Management API

Send a GET request to the /api/v2/custom-domains endpoint: 
curl -L -g 'https://{tenantDomain}/api/v2/custom-domains' \
-H 'Accept: application/json'
The response includes a list of your custom domains, including their status, verification.status and if verified, their certificate.status.
files
{
  "custom_domain_id": "cd_9JPAp8JxtP0jvmbc",
  "domain": "yellow.acmetest.org",
  "primary": true,
  "status": "ready",
  "type": "auth0_managed_certs",
  "verification": {
    "methods": [...],
    "status": "verified",
    "last_verified_at": "2025-06-10T12:49:05Z"
  },
  "tls_policy": "recommended",
  "certificate": {
    "certificate_authority": "letsencrypt",
    "status": "provisioned",
    "renews_before": "2025-09-08T11:52:12Z"
  }
}

​
Verification process

When you first configure an Auth0-managed custom domain, Auth0 attempts to verify the provided custom domain DNS record. The initial custom domain status is set to pending_verification and its verification.status is set to pending.

​
Certification process

Once the DNS record is successfully verified, the custom domain verification.status is set to verified and its certificate.status is set to provisioning. When the certificate is successfully created and deployed, the certificate.status is set to provisioned and the certificate.renews_before attribute indicates the date by which Auth0 will automatically renew the certificate.

​
Troubleshoot

If the verification process fails, the custom domain status is set to failed. You can review the verification.error_msg attribute to determine how to proceed. The verification.error_msg attribute can be set to DNS verification record issue, Domain conflicts with network configuration or CAA record issue.
  • DNS verification record issue: Auth0 could not verify your CNAME or TXT record. This can happen if the record does not exist, is incorrect, or has not propagated yet. Auth0 will attempt to verify the DNS record for up to seven days before failing.
This DNS record must remain in place permanently. Auth0 needs it to automatically renew the certificate in the future.
  • Domain conflicts with network configuration: This typically means that you are using Cloudflare as the DNS provider and Zone Hold is enabled. The Zone Hold prevents Auth0 from verifying your custom hostname. To address this error message:
    1. Remove the Zone Hold from your DNS zone in Cloudflare.
    2. Select Verify in the Auth0 Dashboard > Branding > Custom Domains to restart the process.
    3. Once verification is successful, you can re-enable Cloudflare Zone Hold.
  • CAA record issue: Auth0 cannot get the certificate for your custom domain. This typically is due to your domain’s DNS Certification Authority Authorization (CAA) records restricting which Certificate Authorities can issue certificates for your domain. To address this error message: The easiest solution is to remove your CAA records for the exact custom domain you are trying to verify. This will let Auth0 order and provision the certificate without restrictions. You can determine your current CAA records using the dig command. 
      dig {your-custom-domain.com} +short CAA
    Replace your-custom-domain.com with your actual custom domain.

​
Custom domain is still pending verification

It can take up to 48 hours for the DNS to be propagated.
  • If you continue to see this error in the Dashboard, ensure that the CNAME record is properly configured in your domain management service. You can confirm the configuration of your CNAME record using:
  • Ensure that the domain name is not already associated with an A record.
  • Ensure that no errors were made when typing or copying the CNAME record’s domain name or value.
If you have ensured the above and the custom domain is still pending verification, wait 4 hours before reverifying your domain. To avoid any interruptions to your service, do not recreate the custom domain when reverifying.

​
Cloudflare CNAME flattening

Auth0 recommends turning off CNAME flattening unless it’s strictly necessary, according to the Cloudflare documentation, Understand and configure CNAME flattening. CNAME flattening for Auth0 managed certificates is an unsupported configuration and as such may cause the custom domain to break without notice if CNAME flattening is enabled.
CNAME flattening affects the Auth0 verification and certificate renewal processes due to the way it handles DNS records. Enabling CNAME flattening in Cloudflare after setting up a custom domain does not prevent certificate renewal. If you need to enable CNAME flattening for all subdomains managed by Cloudflare and also configure a specific subdomain to be an Auth0 custom domain, consider delegating the subdomain for Auth0 to another DNS provider. To learn more, read Delegating Subdomains Outside of Cloudflare in the Cloudflare documentation. This will enable you to use CNAME flattening for all subdomains except the one used for Auth0.

​
”You should not be hitting this endpoint”

If you see this error when configuring a custom domain, you must perform additional configurations, which varies depending on your setup. To learn more, see Configure Features to Use Custom Domains.

​
”Service not found”

If your application issues an /authorize request with audience=https://login.acmetest.org/userinfo, the server will return a Service not found: https://login.acmetest.org/userinfo error. This is because even if you set a custom domain the API identifier for the /userinfo endpoint remains https://{yourOriginalAuth0Domain}/userinfo. Similarly, using your custom domain in calls to the Auth0 Management API will error for the same reason. To fix this your app should instead use audience=https://{yourOriginalAuth0Domain}/userinfo. You can also remove this audience=[...]/userinfo parameter altogether if your application is flagged as OIDC-Conformant in the OAuth2 tab of the application’s Advanced Settings.

​
Learn more