Skip to content

CloudFlare API

Todd Knarr edited this page Jul 22, 2017 · 4 revisions

dnsapi.ini record template:

# CloudFlare    Global API key                          Email address
cloudflare      xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   user@domain.com

domains.ini record template:

# CloudFlare                                Zone ID                             TTL
example4.com    example4        cloudflare  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx    1

CloudFlare uses a RESTful JSON-based API for creating records. It requires your global API key and associated e-mail address from your CloudFlare account and the zone ID for the domain you want to update. Copy your global API key and e-mail address into the cloudflare line in dnsapi.ini replacing the x's and "user@domain.com" in the template record. The zone ID goes in the domains.ini file on the line for the domain you want to update, replacing the string of x's in the template record. You may omit the time-to-live (TTL) field, in which case it will default to a value of 1 which CloudFlare interprets as automatic determination of the TTL. If you want to specify a TTL, it's expressed in seconds and a good value would be 3600 (1 hour) since DKIM records don't change often.

CloudFlare has an alternate module identified by using cloudflareapi rather than cloudflare at the beginning of the dnsapis.ini line. The only difference between the two is that the cloudflare module uses the regular requests Python library and a JSON request body to access CloudFlare's API while the cloudflareapi module uses CloudFlare's SDK.

To find your global API key, go into "My Settings" and scroll down to the "API Key" section. You'll find a button there to view the API key and copy it to the clipboard for pasting into dnsapi.ini.

To find the zone ID for a zone the only apparent way is to use the API to list your zones. As of v1.3.1 the package includes the cloudflare_list_zone_ids.py script which will retrieve the list of zones under your account and print out the domain ID and name as a tab-separated list on standard output (status and error logging goes to standard error). It accepts your global API key and account email address, plus an optional domain name if you want to retrieve the ID for just that domain's zone, on the command line. It accepts the standard --help option to print out it's usage information.