Skip to main content

Cloudflare DNS

Cloudflare is the simplest DNS provider to wire up: a single scoped API token with permission to edit DNS records on your zone is all the backend needs. Propagation is fast (seconds), rate limits are generous for DNS-01 volumes.

Prerequisites​

  • A Cloudflare account that owns or has access to the target zone.
  • Permission to create API tokens — the account owner, or a user with the Tokens scope.

Create a scoped API token​

  1. Cloudflare dashboard → My Profile → API Tokens → Create Token.
  2. Pick the Edit zone DNS template (or start from scratch).
  3. Permissions:
    • Zone → DNS → Edit
    • Zone → Zone → Read (for zone lookup; included by the template)
  4. Zone resources: Include → Specific zone → example.com. Zone-scoped tokens contain the blast radius if the token leaks — always prefer them over account-wide tokens.
  5. Optional: Client IP Address Filtering pinned to your backend's egress IP. TTL: a long expiry + a reminder on the calendar beats an unexpected expiry.
  6. Continue to summary → Create Token → copy the token. It is shown once.

Add the credential​

  1. Settings → DNS Credentials → New.
  2. Provider: Cloudflare.
  3. Name: cloudflare-example-prod (pick a descriptive name — listings show it).
  4. API token: paste the token.
  5. Click Test connectivity. The backend creates and immediately deletes a throw-away TXT record on a reachable zone. Success → Save.

Config fields​

FieldRequiredPurpose
api_tokenyesCloudflare API token with Zone:DNS:Edit on the zone.

Propagation​

Cloudflare updates authoritative nameservers within a few seconds. The default propagation strategy (system resolver, 5 s interval, 2 min timeout) is more than enough. Nothing provider-specific to tune.

Rate limits​

Cloudflare allows 1,200 API calls in a 5-minute window per user. A single DNS-01 validation is 2 calls (Present + CleanUp); even the noisiest CertAutoPilot deployment stays orders of magnitude below the limit.

Troubleshooting​

"Invalid API Token"​

Most common cause: the token was copied with leading/trailing whitespace. Regenerate and paste with copy-button; avoid selecting by hand. Less common: the token's zone resource does not include the one you're validating against.

"Zone not found" or "No zone for domain X"​

The zone is either not on this Cloudflare account, or the token's Zone:Zone:Read permission was omitted. Add it and retry.

DNS-01 still fails after 2 minutes​

Check your zone's CAA record — if it restricts issuance to a specific CA and you're asking a different one, the CA's validation step will fail even though the TXT record is there. dig CAA example.com.

See also​