πŸ” Let's Encrypt Wizard
Česky ← Back to the wizard

How to create a Cloudflare API token for DNS-01

For DNS-01 validation through Cloudflare (required for wildcards, handy wherever port 80 is not reachable from the internet) you need a scoped API token β€” not the "Global API Key" (it has rights to your whole account and cannot be restricted).

The token is never entered into the wizard. The wizard does not ask for it, does not store it in the browser and does not put it into the generated scripts, README or ZIP. You type it in when you run issue.sh / issue.ps1 on the server (see below). That is why the generated files are safe to forward.

Steps

  1. Sign in to the Cloudflare dashboard β†’ API Tokens
  2. Click Create Token β†’ Create Custom Token
  3. Set:
    • Token name: letsencrypt-dns (feel free to add the server name so you know where the token lives a year from now)
    • Permissions:
      • Zone β†’ DNS β†’ Edit
      • Zone β†’ Zone β†’ Read
    • Zone Resources:
      • Include β†’ Specific zone β†’ pick your domain (e.g. example.com)
    • Client IP Address Filtering: optionally restrict to the server's public IP
    • TTL: set an expiry (e.g. 1 year) and renew the token after it expires (steps below). A token without expiry only if you understand the risk β€” a leaked token without expiry keeps working until you revoke it by hand.
  4. Continue to summary β†’ Create Token
  5. Copy the token (it is shown only once!) and put it into your password manager β€” you will need it when running the script on the server.

Test the token

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

It should return "status": "active".

Where you enter the token and where it lives afterwards

Linux β€” issue.sh

sudo ls -la /etc/letsencrypt/secrets/
# drwx------ root root .
# -rw------- root root cloudflare.ini

Windows β€” issue.ps1

Revoking and renewing the token (rotation)

  1. In the dashboard Roll the old token (generates a new value with the same permissions) or Delete it and create a new one as above.
  2. On the server run issue.sh / issue.ps1 again β€” it asks for the new token and stores it in the same place (Linux: overwrites cloudflare.ini; Windows: win-acme updates the stored renewal). If the certificate is not yet due, certbot keeps it; a fresh issuance is fine too β€” the hooks take care of deployment.
    • Linux alternative: just sudoedit /etc/letsencrypt/secrets/cloudflare.ini
  3. Rehearse a renewal: sudo certbot renew --dry-run / .\renew-test.ps1 (see troubleshooting).

When to rotate: after expiry (renewals start failing with Authentication error (10000)), on any suspicion of a leak (someone saw the token β€” a ticket, a screenshot, screen sharing), when the server leaves your hands.

Security β€” summary