Skip to main content

DNS Domain Validation (dns-01)

Why use DNS Validation?​

To request a certificate from Let's Encrypt (or any Certificate Authority), you must prove control of the domain names on the certificate. Two ACME challenge types are commonly used:

Wildcard certificates (for example, *.yourdomain.com) can only be requested using DNS validation. DNS validation is also useful when:

  • Your domains are not public websites.
  • Port 80 (HTTP) cannot be used for validation.

How to use DNS Validation​

To validate control of your domains, you create a specific TXT record in the domain's DNS zone for each name on the certificate.

Notes:

  • The TXT value is different for every order/renewal, so automation is strongly recommended.
  • The app includes built‑in integrations for many popular DNS providers with APIs the app can use.

If your DNS provider (or custom DNS setup) does not have a supported API, you can either:

  • Provide your own DNS update script, or
  • Use the Manual DNS option (the request pauses while you update DNS records yourself).

Certify DNS​

Certify DNS is a cloud hosted version of the acme-dns standard (CNAME delegation of acme challenge TXT records to a dedicated challenge response service). This service can be enabled through the https://certifytheweb.com License Keys tab when signed in. The service is compatible with most existing acme-dns clients so it can be used with other ACME clients on all operating systems. Read more about Certify DNS.

DNS API providers​

Current built‑in DNS API providers include:

* Providers marked with an asterisk are community‑contributed and tested by users.

In addition, several providers are supported via the Posh‑ACME project (https://github.com/rmbolger/Posh-ACME). If you encounter issues with these plugins:

  1. Verify the provider works as expected in Posh‑ACME.
  2. Then raise an issue on our GitHub page.

Akamai, AutoDNS, All-Inkl, Bunny, ClouDNS, Combell, Constellix, DMEasy, DNSPod, DNSimple, DomainOffensive, Domeneshop deSEC, DigitalOcean, Dreamhost, Dynu, EasyDNS, Gandi, Google Cloud, Google Domains, Hetzner, HostingDe, Hurricane Electric, Infoblox, Infomaniak INWX IONOS IBM Cloud/SoftLayer, ISPConfig, Leaseweb, Linode, Loopia, LuaDns, name.com, Namecheap NameSilo NS1, PointDNS, Porkbun, PowerDNS, Rackspace, RFC2136, Selectel, Simply, TencentDNS, TotalUptime, UKFast, Yandex, Zilore Zonomi

If you change API credentials, update them under Settings > Stored Credentials so renewals continue to work. Use the Test button to confirm connectivity.

Propagation delay (seconds)​

When using DNS validation, the CA checks your _acme-challenge TXT record via your authoritative name servers. After you update a TXT record, it can take time for all name servers to agree. The app waits for this window, called the propagation delay.

  • Default: 60 seconds
  • If validation is unreliable or your DNS provider is slow to propagate, increase to 120–300 seconds (or more if required)

CNAME delegation​

To avoid updating your primary DNS zone directly, you can use CNAME delegation:

  1. In your primary zone, create an _acme-challenge.<name> CNAME for each domain/subdomain.
  2. Point each CNAME at a corresponding _acme-challenge.<name> TXT record in a different (delegated) zone that you can automate.

In the Authorization configuration UI, set the CNAME Delegation Rule for each authorization configuration.

Rule format: *.source.domain:*.destination.domain (use ; to separate multiple rules).

Example: your site example.com includes example.com and www.example.com. Normally you would create TXT records for _acme-challenge.example.com and _acme-challenge.www.example.com. Instead, you can delegate both to a dedicated zone such as auth.example.org.

  • Configure the authorization to update the target (delegated) domain and set CNAME Delegation Rule to *.example.com:*.auth.example.org.
  • In the original domain, add _acme-challenge CNAMEs pointing to the delegated zone, e.g., _acme-challenge.example.com → _acme-challenge.auth.example.org and _acme-challenge.www.example.com → _acme-challenge.www.auth.example.org.
  • The app will create/update TXT records in the delegated zone using the DNS credentials/API you specified for that zone.

You can also map multiple sources to a single destination subdomain by using a non‑wildcard target. For example, *.example.com:auth.example.org maps _acme-challenge.www.example.com to _acme-challenge.auth.example.org (ignoring the subdomain). Not all DNS providers support multiple TXT values on a single record—check your provider’s capabilities.

Domain match rules​

If a certificate needs multiple authorization configurations (for example, different DNS zones/providers or a mix of HTTP and DNS), use Domain Match Rule to specify which names each configuration applies to. These rules are optional and only used when more than one authorization configuration exists.

Tips:

  • *.example.com matches first‑level subdomains only, not something.subdomain.example.com.
  • Use a semicolon‑separated list to match multiple patterns, e.g., *.example.com;*.subdomain.example.com;www.something.example.com.
  • Use the Preview tab to confirm which identifiers match which configurations. If an identifier is not matched, the app falls back to HTTP validation for that name.

Other DNS validation methods​

You can alternatively use the following methods to manage your DNS TXT records:

acme-dns​

acme-dns automatically manages TXT record values only for challenge validation. If you have access to a trusted acme-dns server, this is often the simplest approach and avoids storing DNS admin credentials on your servers. Learn more: how to use acme-dns.

DNS scripting​

DNS scripting lets you run your own update/delete logic for TXT records. For example, call a .bat file that invokes PowerShell, Python, or Node.js.

Manual DNS​

If you’re experimenting with wildcard domains, you can use manual DNS updates (edit records in your DNS control panel).

This is the least‑recommended option because you must repeat the process for every renewal.

It can also be confusing when requesting a single cert for *.domain.com and domain.com: you must provide two TXT values for the same _acme-challenge.domain.com record (to answer both challenges).

To use Manual DNS:

  1. Select Manual DNS as your DNS update method.
  2. Start the certificate request. When prompted, create the TXT record(s) (one value per name). Wait for DNS propagation—if validation fails, wait longer (up to an hour) and try again.
  3. Use Request Certificate to resume and validate.
  4. If the CA can see the expected TXT values, the order proceeds and the certificate is issued.

Common Issues​

DNS domain validations suddenly failing​

DNS providers can and do change their APIs periodically which can impact renewals using DNS validation. For instance, GoDaddy changed their API to only allow API use for customers with more than 10 domains. Other DNS providers have retired their older APIs resulting in renewals that use those failing. We recommend that if a problem develops with DNS validation that you ensure you are using the latest version of the app and if the problem persists contact your DNS provider to ask if their API has recently changed.