> ## Documentation Index > Fetch the complete documentation index at: https://mintlify-mintlify-e81fe458.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Custom domain > Host your documentation on a custom domain with DNS configuration, automatic TLS certificates, and subdomain or subpath routing options. To host your documentation on a custom domain: 1. Add your domain in your dashboard. 2. Configure DNS settings on your domain provider. 3. Allow time for DNS to propagate and TLS certificates to be automatically provisioned. Looking to set up a subpath like `example.com/docs`? See [/docs subpath](/deploy/docs-subpath). ## Add your custom domain 1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard. 2. Enter your domain name. For example, `docs.example.com` or `www.example.com`. 3. Click **Add domain**. The Custom domain setup page showing the field to enter your custom domain URL. The Custom domain setup page showing the field to enter your custom domain URL. ## Configure your DNS 1. On your domain provider's website, navigate to your domain's DNS settings. 2. Create a new DNS record with the following values: ```text theme={null} CNAME | docs | cname.mintlify.builders ``` Each domain provider has different ways to add DNS records. Refer to your domain provider's documentation for specific instructions. Do not add or change your `CNAME` until both verification `TXT` records show as verified in your dashboard. Each appears with a green check when DNS is correct. The dashboard verifies `TXT` records before certificate provisioning can complete. Switching `CNAME` too early commonly breaks HTTPS until provisioning finishes. If you migrate an existing domain and want zero downtime, publish the verification `TXT` records first and wait until they show verified and TLS has pre-provisioned before pointing `CNAME` at Mintlify. This pre-validation flow does not work for domains proxied through Cloudflare. See [Cloudflare-proxied domains](#cloudflare-proxied-domains). ### Verification TXT records After you add a custom domain, the dashboard displays two `TXT` records that you must add at your DNS provider: ```text theme={null} TXT | _acme-challenge. | TXT | _cf-custom-hostname. | ``` The `_acme-challenge` record authorizes Let's Encrypt to issue a TLS certificate for your domain, and the `_cf-custom-hostname` record verifies that you control the domain. The dashboard polls DNS in the background and marks each record with a green check once it verifies the expected value. After saving records at your DNS provider, allow a short time for propagation before status updates appear. ### DNS propagation DNS changes typically take 1-24 hours to propagate globally, though it can take up to 48 hours in some cases. Use a tool like [DNSChecker](https://dnschecker.org) to verify your DNS configuration is correct. Once your DNS records are active, your documentation is first accessible via HTTP. HTTPS is available after Mintlify provisions your TLS certificate. ### Automatic TLS provisioning After you add your `TXT` records and your DNS records resolve correctly, Mintlify generates a free SSL/TLS certificate for your site using Let's Encrypt. This typically completes within a few hours of DNS propagation, though it can take up to 24 hours in rare cases. Certificates are automatically renewed before expiration. ### CAA records If your domain uses CAA (Certification Authority Authorization) records, you must authorize Let's Encrypt to issue certificates for your domain. Add the following CAA record to your DNS settings: ```text theme={null} 0 issue "letsencrypt.org" ``` ### Reserved paths Mintlify reserves the `/.well-known/acme-challenge` path for certificate validation. You cannot redirect or rewrite this path. If you have configured redirects or rewrites for this path, certificate provisioning fails. ### Cloudflare-proxied domains If your domain is already proxied through Cloudflare (the proxy status shows an orange cloud), the verification `TXT` records cannot show as verified before you update your `CNAME`. This happens even when the records resolve correctly with tools like `dig` or DNSChecker. Cloudflare's proxy prevents the verification from completing until traffic for the hostname routes to Mintlify. For Cloudflare-proxied domains, follow these steps: 1. Add the verification `TXT` records at your DNS provider. 2. Update your `CNAME` record to point to `cname.mintlify.builders` without waiting for the `TXT` records to show as verified. 3. Wait for verification and TLS provisioning to complete. Your site may briefly serve an invalid certificate during provisioning. If you need zero downtime during migration, set the `CNAME` record's proxy status to **DNS only** (gray cloud) instead. This allows the standard pre-validation flow to complete before you switch traffic. ### Provider-specific settings If Cloudflare is your DNS provider, you must enable the "Full (strict)" mode for the SSL/TLS encryption setting. Additionally, disable "Always Use HTTPS" in your Edge Certificates settings. Cloudflare's HTTPS redirect blocks Let's Encrypt from validating your domain during certificate provisioning. ### Retry validation If your domain is still pending validation after adding the verification `TXT` record, you can retry validation manually from your dashboard. 1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard. 2. Find your pending custom domain. 3. Click **Retry validation**. Only retry validation after you confirm that your DNS records are correct. Repeated retries with incorrect records do not speed up validation. ## Lifecycle and ongoing maintenance ### `_acme-challenge` TXT values change over time The value shown for the `_acme-challenge.` `TXT` record is not permanent. Let's Encrypt issues a new certificate before each renewal, and every issuance requires a fresh validation token. When Mintlify rotates the certificate, the dashboard updates the `_acme-challenge` value your DNS provider needs to serve. This is expected behavior, not a misconfiguration: * Keep the `_acme-challenge` record in place. Do not delete it after the initial validation. * Whenever the dashboard shows a new value for `_acme-challenge`, update the `TXT` record at your DNS provider to match. The domain continues to work on the existing certificate until it expires, so you have time to update the record. * If the value drifts and you do not update DNS, the next renewal fails and HTTPS eventually breaks. Retry validation from the dashboard after you save the new value. The `_cf-custom-hostname` value, in contrast, is stable for the lifetime of the custom hostname. ### The default `.mintlify.app` URL Every deployment keeps a default URL at `.mintlify.app` even after you add a custom domain. This URL is used internally for previews, dashboard links, integrations that reference the deployment by its subdomain, and as a fallback during custom-domain provisioning. It cannot be disabled. If you want end users to always land on your custom domain: * Set a [canonical URL](#set-a-canonical-url) so search engines index the custom domain instead of `.mintlify.app`. * Redirect the `.mintlify.app` URL to your custom domain from your own layer if needed. Mintlify does not add this redirect automatically. ### Rename a deployment subdomain Renaming the deployment subdomain in the dashboard changes the `.mintlify.app` URL and the internal origin that your custom domain rewrites to. After a rename: * Existing custom domains stay attached, but their KV configuration needs to be refreshed so the proxy points at the new origin. Save the custom domain again from the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page to trigger the refresh. * Any external service that references the old `.mintlify.app` URL (webhooks, OAuth redirect URIs, analytics allowlists, CSP rules, reverse-proxy rewrites) must be updated to the new subdomain. * Update any hardcoded links or canonical URLs in `docs.json` that referenced the old subdomain. If your custom domain returns a `502` with `Disallowed origin host` after a rename, see [Troubleshooting](#troubleshooting). ### Release a custom domain held by another organization A custom domain can only be attached to one Mintlify deployment at a time. If you try to add a domain that is already claimed by another organization or a previous project, the dashboard blocks the add and reports that the domain is in use. To move the domain to a new organization or deployment: 1. From the organization that currently owns the domain, navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page and remove the custom domain from the existing deployment. 2. In the new organization, add the domain on the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page and complete the DNS verification steps again. If you no longer have access to the organization that holds the domain, contact [Mintlify support](mailto:support@mintlify.com) from the email address associated with the domain's DNS or ownership so we can release it. Include the domain and, if possible, the previous organization or deployment name. ### Remove a custom domain To detach a custom domain from a deployment: 1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard. 2. Remove the domain. 3. Delete the `CNAME` and verification `TXT` records at your DNS provider once the domain is no longer needed. Leaving stale records in place is safe but can be confusing later. After removal, the domain is immediately available to be added to another deployment or organization. ## Advanced routing scenarios ### Multiple projects under one custom domain To serve multiple Mintlify deployments from a single custom domain, use subpaths and a reverse proxy or edge worker. Each deployment keeps its own `docs.json`, subdomain, and dashboard, and your proxy decides which deployment serves each path. Example layout on `example.com`: * `example.com/product-a` → deployment `product-a` * `example.com/product-b` → deployment `product-b` * `example.com/api` → deployment `api-docs` To set this up: 1. For each deployment, configure a [`/docs` subpath](/deploy/docs-subpath) using [Cloudflare](/deploy/cloudflare), [Route 53 and CloudFront](/deploy/route53-cloudfront), [Vercel](/deploy/vercel), or a [custom reverse proxy](/deploy/reverse-proxy). Set a different base path for each deployment. 2. In each deployment's `docs.json`, set the `canonical` URL to the fully-qualified subpath (for example, `https://example.com/product-a`) so search engines index the correct URL. 3. Point a single `CNAME` for the shared domain at your proxy or edge worker, not directly at `cname.mintlify.builders`. The proxy is responsible for forwarding each subpath to the correct Mintlify origin. Adding the same custom domain to more than one deployment directly in the Mintlify dashboard is not supported. The subpath routing must happen at your own proxy layer. ### Redirecting multiple domains to one deployment Attaching more than one custom domain to a single deployment as an automatic redirect is not currently supported. Each deployment has one primary custom domain. If you need `docs.old-brand.com` and `docs.new-brand.com` to both resolve to the same content, choose one of these workarounds: * Set the domain you want as the canonical destination as the deployment's custom domain, then configure a redirect from the other domain to it at your DNS provider or CDN (for example, a Cloudflare page rule, a Vercel redirect, or an AWS CloudFront function). * Redirect at the registrar level if your registrar offers domain forwarding. Set a [canonical URL](#set-a-canonical-url) that matches the primary domain so search engines consolidate ranking on a single hostname. ## Troubleshooting ### `502 Disallowed origin host` This error is returned by the Mintlify edge proxy when a custom domain's stored origin no longer matches an allowed Mintlify hostname. It most often appears after: * The deployment's subdomain was renamed and the custom domain's cached rewrite still points at the old `.mintlify.app` origin. * A custom domain was moved between deployments or organizations without refreshing the configuration. To resolve: 1. Navigate to the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard. 2. Remove and re-add the custom domain, or click **Retry validation** to force the origin to be re-written. 3. If the error persists after a few minutes, contact [Mintlify support](mailto:support@mintlify.com) with the affected custom domain and current deployment subdomain so we can refresh the edge configuration. ### Validation stays pending after DNS is correct * Confirm both `_acme-challenge` and `_cf-custom-hostname` `TXT` records resolve with the expected values using [DNSChecker](https://dnschecker.org) or `dig`. * If the `_acme-challenge` value in your dashboard changed since you first saved the record, update DNS with the new value (see [`_acme-challenge` TXT values change over time](#_acme-challenge-txt-values-change-over-time)). * For Cloudflare-proxied domains, see [Cloudflare-proxied domains](#cloudflare-proxied-domains). The verification cannot complete until traffic routes through Mintlify. * Only click **Retry validation** after DNS is confirmed correct. ## Set a canonical URL After configuring your DNS, set a canonical URL to ensure search engines index your preferred domain. A canonical URL tells search engines which version of your documentation is the primary one. This improves SEO when your documentation is accessible from multiple URLs and prevents issues with duplicate content. Add the `canonical` meta tag to your `docs.json`: ```json theme={null} "seo": { "metatags": { "canonical": "https://www.your-custom-domain-here.com" } } ``` Replace `https://www.your-custom-domain-here.com` with your actual custom domain. For example, if your custom domain is `docs.mintlify.com`, you would use: ```json theme={null} "seo": { "metatags": { "canonical": "https://docs.mintlify.com" } } ```