Join my community / free newsletter — sign up here

Cloudflare API: Safer DNS Automation for Launches and Migrations

Illustrated infographic summarizing: Cloudflare API: Safer DNS Automation for Launches and Migrations

By Greg Nowak. Updated August 9, 2026.

Cloudflare’s dashboard is perfectly adequate for an occasional DNS edit. The API earns its place when DNS becomes part of a launch checklist, migration, client onboarding process, or agency handover.

The business case is not automation for its own sake. It is having a change that can be inspected before traffic moves, repeated without relying on memory, and understood by the next person responsible for the domain. A short, well-documented shell script is often enough.

Choose the smallest workflow that controls the risk

Manual work is not automatically unsafe, and scripts are not automatically reliable. Match the method to the change, its consequences, and whether somebody will need to repeat or review it.

Situation Recommended approach Control that matters
One low-risk edit Cloudflare dashboard Second-person check for important records
Launch or migration Read, review, then write through the API Exact zone, name, type, content, and proxy status
Agency handover Versioned script and sample configuration Clear ownership and record comments
Bulk zone move Export, clean, review, then import Saved pre-change zone file
CI preflight Read-only API token No write permission in the checking job
A practical decision matrix for DNS work: use the lightest method that still leaves the change reviewable and recoverable.

Scope the token to the job and the zone

Use an API token instead of Cloudflare’s broad Global API key. Inventory and preflight jobs normally need DNS Read; record changes and imports need DNS Write. Restrict the token to the relevant zone and consider an expiry or client-IP restriction when the operating environment supports it.

A user token suits ad hoc work performed by a named operator. For durable CI/CD or service integrations, an Account API token can avoid tying an important process to an employee account, provided the required endpoint supports it. Keep the token in a secret store. The zone ID is configuration rather than a secret and can live in an approved CI variable.

: "${CLOUDFLARE_API_TOKEN:?set by your secret store}"
: "${ZONE_ID:?set as deployment configuration}"
CF_API='https://api.cloudflare.com/client/v4'

curl --fail-with-body --silent --show-error \
  "$CF_API/user/tokens/verify" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

If a script discovers the zone with GET /zones, its token also needs Zone Read. For a tightly scoped DNS job, copying the zone ID from the dashboard during setup avoids adding that permission merely for discovery.

Read the exact record before writing

The dangerous pattern is a script that immediately sends a create or update request. Start by filtering on both the fully qualified name and record type. Review the returned ID, content, TTL, and proxy status before deciding what should happen.

curl --fail-with-body --silent --show-error --get \
  "$CF_API/zones/$ZONE_ID/dns_records" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --data-urlencode "type=A" \
  --data-urlencode "name=app.example.com"

Make the script stop if the result is ambiguous. Zero matches can lead to a reviewed POST; one match can lead to a PATCH using that record’s ID; multiple matches should require a human decision. This makes reruns safer and prevents a creation script from quietly accumulating unintended records.

curl --fail-with-body --silent --show-error \
  "$CF_API/zones/$ZONE_ID/dns_records/$DNS_RECORD_ID" \
  --request PATCH \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"content":"198.51.100.4","ttl":3600,"proxied":true,"comment":"App origin - OPS-142"}'

Cloudflare’s current record rules still matter: A and AAAA records cannot share a name with a CNAME, while an NS record cannot share its name with another record type. A TTL of 1 means automatic; otherwise the documented range is 60–86,400 seconds, with a 30-second minimum available on Enterprise zones.

Leave business context beside the record

Comments do not affect DNS responses, but they can explain why a record exists. Add a ticket number, system owner, migration reference, or planned removal date. Comments are available on every plan; tags are useful for grouping records but are limited to paid plans. Keep the authoritative detail in your project system and use the DNS comment as a concise pointer.

Treat imports as migrations, not uploads

For bulk work, export the current zone before changing it. Store that file with the approved change request, review the proposed zone file separately, and import only after checking mail, verification, delegation, and origin records—not just the website’s A and CNAME records.

curl --fail-with-body --silent --show-error \
  "$CF_API/zones/$ZONE_ID/dns_records/export" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --output zone-before-change.txt

curl --fail-with-body --silent --show-error \
  "$CF_API/zones/$ZONE_ID/dns_records/import" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --form "[email protected]"

Cloudflare currently limits zone files to 256 KiB and import/export API traffic to three requests per minute per user. Targets for records such as CNAME, MX, NS, PTR, and SRV should be fully qualified names ending with a period. Cloudflare supports $ORIGIN, $TTL, and $GENERATE, but not $INCLUDE. Reserved cf-proxied:true and cf-proxied:false tags preserve intentional proxy state during import.

Build the handover into the automation

For coordinated multi-record work, Cloudflare’s batch endpoint can apply deletes, patches, puts, and posts in one database transaction. Network propagation is still not atomic, so do not assume every resolver will observe every change simultaneously.

  1. Version the script and reviewed sample inputs.
  2. Keep tokens out of source code and shell-history examples.
  3. Record who approves and who executes production changes.
  4. Export before bulk operations and document the rollback decision.
  5. Verify the public DNS result after the change, from outside the Cloudflare account.

If DNS keeps becoming a fragile part of launches or client handovers, Greg can help turn the commands into a dependable operating process that your team can review, run, and maintain.

Related on GrN.dk

Need help with this kind of work?

Discuss a safer DNS workflow with Greg Get in touch with Greg.

Sources

Last modified
2026-08-09

Tags