DNS-01 Challenge: How It Works and How to Complete It

DNS-01 is the ACME challenge type that supports wildcard certificates (*.example.com). It proves domain ownership by adding a TXT record to your DNS — no web server or port 80 access needed.

How it works

1. Let’s Encrypt provides a token for each domain
2. GetHTTPS computes a SHA-256 digest of the key authorization and base64url-encodes it
3. You create a TXT record at _acme-challenge.yourdomain.com with this value
4. Let’s Encrypt queries public DNS for the TXT record
5. If the value matches, the challenge passes and the certificate is issued

With GetHTTPS, steps 1-2 are automatic — you just copy-paste the record name and value into your DNS provider.

Step-by-step setup

Step 1: Get the TXT record details from GetHTTPS

GetHTTPS shows you:

• Record name: _acme-challenge.yourdomain.com
• Record value: a base64url-encoded string (~43 characters)

Step 2: Add the TXT record at your DNS provider

Provider-specific instructions:

Cloudflare

1. Dashboard → your domain → DNS → Records → Add record
2. Type: TXT, Name: _acme-challenge, Content: paste value
3. TTL: Auto
4. Click Save

AWS Route 53

1. Hosted zones → your domain → Create record
2. Record name: _acme-challenge
3. Record type: TXT
4. Value: "paste-value-here" (include the double quotes — Route 53 requires them)
5. TTL: 300
6. Click Create records

GoDaddy

1. DNS Management → Add
2. Type: TXT, Name: _acme-challenge, Value: paste value
3. TTL: 1 Hour (lowest available)
4. Click Save

Namecheap

1. Domain List → Manage → Advanced DNS → Add new record
2. Type: TXT, Host: _acme-challenge, Value: paste value
3. TTL: Automatic
4. Click Save all changes

Google Cloud DNS

gcloud dns record-sets create _acme-challenge.yourdomain.com. \
  --zone=your-zone --type=TXT --ttl=60 --rrdatas="the-value"

DigitalOcean

1. Networking → Domains → your domain → Add record
2. Type: TXT, Hostname: _acme-challenge, Value: paste value
3. TTL: 30

Step 3: Wait for DNS propagation

DNS changes take 1-15 minutes depending on your provider and TTL settings. GetHTTPS’s pre-check verifies the TXT record is visible from the public internet before submitting to Let’s Encrypt.

Check propagation manually:

dig TXT _acme-challenge.yourdomain.com +short
# Should return your value (in quotes)

Or use an online propagation checker to see if the record is visible globally.

Step 4: Verify in GetHTTPS

Click Verify. GetHTTPS submits the challenge to Let’s Encrypt. If the TXT record is correct, the certificate is issued.

Step 5: Clean up

After the certificate is issued, delete the _acme-challenge TXT record from your DNS. It’s no longer needed and leaving stale records can cause confusion during renewal.

Wildcard certificates with DNS-01

To get a certificate for *.yourdomain.com, you must use DNS-01. HTTP-01 cannot validate wildcards because a wildcard covers infinite hostnames — there’s no single server to place a file on.

Wildcard + bare domain: If you want both *.example.com and example.com, GetHTTPS may require two validations. Some setups need two TXT records at _acme-challenge.example.com simultaneously — one for the wildcard, one for the apex. Keep both records until validation passes.

Full wildcard certificate guide →

DNS-01 vs HTTP-01

Choose DNS-01 when: you need a wildcard, port 80 is blocked, your server isn’t publicly accessible, or you’re behind a CDN.

Choose HTTP-01 when: you have a web server, port 80 is open, and you don’t need a wildcard. It’s faster (no propagation wait).

Troubleshooting

TXT record not found by GetHTTPS

• Wait longer — some providers take 5-15 minutes. Low TTL helps but doesn’t eliminate propagation time.
• Check the record name: Some providers auto-append the domain. If you enter _acme-challenge.example.com and the provider appends .example.com, the actual record becomes _acme-challenge.example.com.example.com (wrong). Enter just _acme-challenge and let the provider append.
• Verify manually:

  dig TXT _acme-challenge.yourdomain.com +short

  If this returns empty, the record isn’t propagated yet.

Wrong value / case mismatch

• The value is case-sensitive. Copy-paste directly from GetHTTPS — don’t re-type it.
• Don’t add quotes unless your DNS provider requires them (Route 53 does, most others don’t).

Multiple TXT records conflict

• Remove old _acme-challenge TXT records from previous attempts before adding new ones.
• Exception: wildcard + apex validation may need two records at the same name simultaneously.

DNS provider doesn’t support TXT records

Rare, but some basic DNS services lack TXT support. Switch to a full-featured DNS provider (Cloudflare’s free plan supports all record types).

When to use DNS-01

Frequently asked questions

Can I automate DNS-01 challenges?

Yes, with CLI tools. acme.sh has built-in API integrations for 150+ DNS providers — it can add and remove TXT records automatically. Certbot supports DNS plugins for major providers. GetHTTPS requires manual DNS changes (browser-based, no API calls).

Is it safe to give an ACME client my DNS API key?

The API key has write access to your DNS zone, so treat it with the same security as your server credentials. Use scoped API tokens when possible (e.g., Cloudflare’s per-zone tokens). For maximum security, use GetHTTPS with manual DNS changes — no API keys involved.

How long do I need to keep the TXT record?

Only during validation — typically a few minutes. Once your certificate is issued, delete the record. You’ll create a new one with a new value when you renew.

What if my DNS provider is slow to propagate?

Set the TTL as low as your provider allows (ideally 60 seconds). If propagation takes longer than 15 minutes, check for typos in the record name/value, or try a different DNS provider. Cloudflare propagates TXT records within seconds.

Does DNS-01 work with Cloudflare proxy (orange cloud)?

Yes. DNS-01 validation queries the TXT record via DNS, not HTTP — so the Cloudflare proxy status (orange vs gray cloud) doesn’t matter. This is a key advantage over HTTP-01, which can be blocked by the proxy.