Learn how the Let’s Encrypt DNS-01 challenge works, when it is preferable to HTTP-01, and how to publish, verify, and automate the TXT records needed for wildcard and other certificates.
Overview
Before Let’s Encrypt issues a certificate, it must confirm that you control the requested domain. With the DNS-01 challenge, the certificate client proves control by placing a unique value in a DNS TXT record. Let’s Encrypt then looks up that record and compares it with the value expected for the certificate request.
The record is normally published at _acme-challenge.example.com. You do not place it on the website server, and the TXT value is not the certificate itself. It is a short-lived authorization value used during validation.
DNS-01 is especially useful when the certificate must cover a wildcard name such as *.example.com. HTTP-01 cannot validate wildcard certificates, while DNS-01 can. DNS validation can also be useful when the web server is not publicly reachable on the required HTTP port, when several servers sit behind a load balancer, or when certificate issuance is managed separately from web hosting.
There is an important scope distinction: a certificate for *.example.com generally covers names such as www.example.com and api.example.com, but not the bare example.com or a deeper name such as v2.api.example.com. Request the names your applications actually use.
Core framework
1. Choose DNS-01 for the right reason
Use HTTP-01 when a simple, public website can reliably serve a challenge file over HTTP. Choose DNS-01 when you need a wildcard certificate, cannot route the challenge to the correct server, or want validation to work independently of the application infrastructure.
DNS-01 adds a different operational responsibility: the certificate client needs a way to create and remove DNS records. Manual entry can work for an occasional certificate, but it is a poor fit for unattended renewal because every renewal would require human intervention.
2. Create the correct TXT record
When the ACME client starts a DNS-01 validation, it displays or creates a token. The token belongs in a TXT record whose name is usually _acme-challenge relative to the domain being validated. Depending on the DNS control panel, the full record name may be shown as _acme-challenge.example.com, while another panel expects only _acme-challenge.
Enter the value exactly as supplied. Do not add explanatory text, alter punctuation, or paste quotation marks unless the DNS interface specifically requires them. TXT records may be displayed with quotation marks by a DNS tool even though those marks are not part of the value.
DNS supports multiple TXT values at the same name. This matters when more than one validation is active. Do not delete an existing ACME TXT value simply because a new one appears; remove stale values only when you are confident that no active validation or renewal still needs them.
3. Allow authoritative DNS to answer
The record must be published by the authoritative DNS provider for the domain. Adding a TXT record to a hosting dashboard does nothing if the domain’s nameservers point elsewhere. Start troubleshooting by checking which nameservers are authoritative, then inspect the record through more than one independent DNS resolver.
Propagation is not a single global switch. Recursive resolvers can retain an earlier answer until its time to live, or TTL, expires. A record may appear in one lookup and remain absent in another for a period of time. Wait for the authoritative servers to return the new value before repeatedly retrying certificate issuance.
4. Automate carefully
For production renewals, use an ACME client with a DNS provider integration or a supported DNS API hook. The integration should create the TXT record, wait for DNS visibility, ask Let’s Encrypt to validate it, and remove the record afterward where appropriate.
Give the automation a narrowly scoped API credential. If the provider supports permissions limited to DNS records for one zone, prefer that over an account-wide credential. Store the secret outside source control, protect its file permissions, and avoid placing it in shell history or publicly visible logs. Test renewal before the certificate approaches expiration, and monitor both the renewal job and the resulting certificate.
A CAA record can also express which certificate authorities may issue for a domain. If you use CAA, ensure its policy permits the certificate authority and applies consistently across the relevant DNS hierarchy. See our CAA records guide for configuration considerations.
Practical examples
Manual DNS-01 with a single domain
- Run your ACME client in a mode that requests a DNS-01 challenge for
example.com. - Copy the generated token and publish it as a TXT record at
_acme-challenge.example.com. - Use a DNS lookup tool to confirm that the authoritative nameservers return the expected TXT value.
- Return to the client and allow validation to continue.
- Remove the temporary record after the client confirms completion, unless another active validation uses the same name.
This method is suitable for learning, testing, or infrequent issuance. It is not a dependable renewal strategy for certificates that must renew without an operator present.
Wildcard issuance through a DNS provider
A typical automated request includes both the wildcard and apex names when both are needed, for example example.com and *.example.com. The client creates the required TXT value through the provider’s API, waits for it to become visible, and completes validation. The DNS credential remains on the certificate host or automation system, not in the web application’s repository.
If your provider offers a dedicated ACME plugin, follow that plugin’s documentation for credential format, zone selection, propagation delay, and cleanup behavior. Cloudflare DNS and other providers can be used for this workflow, but the exact commands and permissions depend on the client and provider integration you choose.
For the web-server side of the deployment, review our Nginx and Apache installation guide. Certificate issuance and HTTPS configuration are related but separate tasks: passing DNS validation does not automatically configure every server or application to use the new certificate.
Common mistakes
- Editing the wrong DNS provider: Confirm the domain’s authoritative nameservers before adding the TXT record.
- Using the wrong record name: Check whether the control panel automatically appends the zone name. Accidentally creating
_acme-challenge.example.com.example.comis a common error. - Deleting a second TXT value: Parallel authorizations may require multiple values at the same name. Preserve values until their validations finish.
- Expecting instant propagation: Query authoritative servers and allow for caching instead of submitting repeated failed attempts.
- Using a broad API key: Limit DNS credentials to the smallest zone and permission set available, and rotate them if exposure is suspected.
- Assuming a wildcard covers everything: Include the apex domain and deeper subdomain names explicitly when the certificate needs them.
- Relying on manual renewal: A certificate can be issued successfully today and still fail later when nobody is available to publish the next TXT value.
When an authorization fails, inspect the exact domain named in the error, query the TXT record from the authoritative servers, and confirm that the returned value matches the current challenge. For broader troubleshooting, see the Let’s Encrypt error codes guide.
When to revisit
Review your DNS-01 setup whenever you change DNS providers, nameservers, hosting architecture, certificate client, or API credentials. Recheck it before migrating a website, splitting services across zones, or introducing a new wildcard name. A migration checklist can help preserve DNS and certificate automation during a host move; see our website migration guide.
As a practical maintenance routine, test the renewal command in a safe environment, verify that the DNS integration can create and remove records, and confirm that monitoring will alert you when renewal fails. Keep a written record of the authoritative DNS provider, zone, client configuration, credential owner, and certificate names. If you prefer a conventional certificate workflow for non-wildcard sites, compare it with the Nginx and Apache renewal guidance in our Certbot automation guide.
The dependable DNS-01 pattern is simple: publish the exact TXT value in the authoritative zone, verify it before asking for validation, automate with least privilege, and monitor renewal rather than assuming issuance will remain healthy indefinitely.
