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,
READMEor ZIP. You type it in when you runissue.sh/issue.ps1on the server (see below). That is why the generated files are safe to forward.
Steps
- Sign in to the Cloudflare dashboard β API Tokens
- Click Create Token β Create Custom Token
- 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βEditZoneβ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.
- Token name:
- Continue to summary β Create Token
- 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
- The script prompts for the token with
read -s(not echoed, not written to shell history). - It stores it only in
/etc/letsencrypt/secrets/cloudflare.iniβ directory mode700, file mode600, owned byroot. Permissions are set before anything is written. - On every renewal certbot reads it from there (
--dns-cloudflare-credentials); you never type it again.
sudo ls -la /etc/letsencrypt/secrets/
# drwx------ root root .
# -rw------- root root cloudflare.ini
Windows β issue.ps1
- The script prompts with
Read-Host -AsSecureStringand hands the token to win-acme (--cloudflareapitoken). - win-acme stores it encrypted (Windows DPAPI) in its renewal configuration (
C:\ProgramData\win-acme\<acme-server>\Renewals\) so scheduled renewals work without you. It can only be decrypted on this machine by the account that stored it. - If you do not want to pass the token on the command line even once (PowerShell history, logs), use the win-acme secret vault:
wacs.exe --vaultβ store the token under the keycloudflareand use the referencevault://json/cloudflarein the script instead of the value. The generatedissue.ps1describes this option in a comment.
Revoking and renewing the token (rotation)
- 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.
- On the server run
issue.sh/issue.ps1again β it asks for the new token and stores it in the same place (Linux: overwritescloudflare.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
- Linux alternative: just
- 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
- Only you (when typing it) and your server ever see the token. The wizard, the generated scripts and the ZIP never contain it.
- Least privilege: one zone,
DNS:Edit+Zone:Read, an expiry, optionally an IP filter. - Never paste it into tickets, e-mails or bug reports.
- Compromised β Delete/Roll in the dashboard immediately, then rotate on the server (above).