Backing up and restoring your Cloudflare account configuration

Most backup products treat your Cloudflare account as the place a backup runs, not as a thing that itself needs backing up. But your DNS, WAF rules, Access policies and zone settings are configuration you would rebuild by hand if lost or wrongly changed. The cf-config source captures that configuration as a first-class source type, alongside your KV, R2, D1 and Secrets Store data and your Worker code, so a snapshot of your account’s posture is part of the same signed, verified archive as your data.

This page covers the cf-config source and its tiered restore: what configuration is captured, the read-only credential the backup uses, the separate one-shot edit token a restore needs, and what auto re-applies versus what you must re-create out of band.

The headline scope is one registry of 313 Cloudflare config surfaces. Of those, 60 auto-restore in-band: the engine diffs your live config against the snapshot and re-applies straight back into your account through the console. 228 are backup-and-preview only: they are captured in full and verified recoverable, and a restore previews the tier-specific guidance for re-applying each one out of band (dependency order, or a re-provision checklist), rather than a diff against live. The 25 in between carry a writer that is off by default, so a default restore leaves them alone and only a request that names the surface reaches one. A default restore therefore writes back the 60 and nothing else. The sections below explain why the split falls where it does.

What cf-config captures

A cf-config downpipe snapshots one Cloudflare account, and optionally one zone within it. Each configuration surface backs up as a single archived record. The record name is the surface id, and the value is that surface’s configuration as canonical JSON. The surface registry is deliberately generous: it covers everything configuration-shaped so that an account simply gets a marker for any product it does not use, rather than the snapshot failing.

The surfaces span the configuration you would expect to rebuild after an incident.

Configuration is the scope, not data and not runtime. Your KV namespaces, R2 buckets, D1 databases and Secrets Store entries are their own data source types, captured separately. Logs, analytics, Stream and Images content and compute deployments are out of scope. Billing is excluded by design. Registrar is captured, at the re-provision tier and with the ordinary read-only discovery token rather than the Global API Key, which the engine deliberately never holds; what a restore cannot replay there is the registry-side state, meaning transfer locks and authorisation codes.

Choosing what to capture: mode and scope

Two controls decide how much of your Cloudflare configuration a downpipe backs up.

The capture mode is Auto or Manual. Auto, the default, backs up the configuration surfaces actually in use: the engine discovers them, refreshes that set daily, and a run reads only what exists, so it stays cheap as your configuration changes. The downpipe’s drawer shows the current mode, when the surfaces were last discovered and how many are in use, unused or unavailable. A Rediscover control forces a fresh probe. Manual instead backs up exactly the surfaces you tick, for when you want a fixed, audited set rather than whatever is live. A downpipe with a non-empty surface list reads as Manual; an empty list reads as Auto.

From engine 0.3.6, each run also carries one coverage record. It names each registry surface that the run has no record for, with the reason: not used, not on your plan, no zone selected, or not selected. The record also states whether the reasons come from the daily discovery or from your selection. An archive read years later then tells “your plan did not include this” apart from “this was not captured”. The coverage record is not a surface, so a restore does not write it back. From reader 0.3.4, the offline reader also labels it as information, not as a surface to replay.

The scope, when you protect a zone, is one of three presets. “Account configuration only” backs up the account-wide settings, the Zero Trust, notifications and rulesets surfaces, about one hundred and ninety-five of them, and no per-zone configuration. “This zone only” backs up just the ticked zone’s DNS, WAF and zone settings. “Account + this zone” backs up both. Choosing a scope when you protect several zones at once avoids duplicating the shared account configuration into every zone’s downpipe.

The credential model

Backup and restore use two different credentials, and the asymmetry is the point.

Backup reads the Cloudflare REST API with the engine’s existing read-only discovery token, the same token a self-hoster widens to the “Read all resources” template for full per-zone coverage. There is no per-downpipe key and no edit scope on the backup path. The account and zone a downpipe covers are fixed for its life; only the surface selection is editable.

Permission groups the “Read all resources” template does not reliably include

Cloudflare does not publish the exact permission list behind the “Read all resources” template, and it is not a fixed set: it is Cloudflare’s broadest generic template, and several of the registry’s surfaces sit in permission groups the template does not carry. This is not a plan gate. An account can genuinely use Access, Gateway or Logpush and still have the discovery token come back unavailable on those surfaces, because the token was never granted the group, not because the account does not carry the product.

For example, on an account that runs Cloudflare Access day to day (existing Access applications, an identity provider, enforced policies), a discovery token minted from the template alone still reads access-groups as unavailable, because “Read all resources” does not carry the Access permission groups. The account has Access; the token does not have the scope. Do not read this as “my plan does not include this.”

If your account uses any of the following, add the matching permission group explicitly, at Read, when you create the token, rather than relying on the template to have included it:

This list is not exhaustive; it names the permission groups known to be missing from the template, not every group the 313-surface registry could ever touch. Build the token from evidence rather than from a fixed checklist: create it, attach a downpipe, press Rediscover, and read the drawer’s unavailable count. Zero is the token reaching everything the account actually uses. Anything above zero is a permission group still to add, not a plan the account does not have; open the config surface reference to find which surfaces the unavailable count covers and work back to the permission group from the table above.

Restore needs a separate, edit-scoped Cloudflare API token, and you supply it in the restore request itself. That token is never stored, never written to a log, and never folded into the dual-control approval hash. Only the non-secret account id and optional zone id are bound into the approval. So a restore approval can be shown, copied and recorded without ever leaking the edit credential.

Not being stored has one practical consequence worth planning for. The token lives only in the restore form you typed it into. Reload that screen, or come back to it later, and the field is empty; enter the token again and build the plan again. That costs you nothing beyond the rebuild, because the token is not part of the plan hash: the same request hashes identically, so an approval already granted against it still matches (restorePlanHash, console/src/lib/api/helpers.ts, recomputed server-side in engine/src/admin/approvals.ts).

The account id and zone id are non-secret Cloudflare identifiers, each a 32-character hexadecimal string. Your account id is on the Cloudflare dashboard as the Account ID in the right-hand column of an account’s overview; a zone id is on that zone’s own overview page in the API panel. Supply the account id that the config was backed up from. The zone id is required only for zone-scoped surfaces such as DNS and page rules, so leave it blank for an account-only restore.

Which permissions the edit token needs

You create this token the same way as any Cloudflare API token: My Profile, then API Tokens, then Create Custom Token. The scopes it needs follow directly from the surfaces that write back in-band, because each one calls a specific Cloudflare API. Grant each permission below at the Edit access level, and only for the surfaces you actually intend to restore.

You do not have to grant all of them. The apply works surface by surface and fails open per item, so a surface your token cannot write is skipped with a coarse “the token was rejected or lacks the edit scope” reason rather than failing the rest of the restore. Scope the token to the surfaces you are restoring, to the one account, and to the specific zone for the zone-level permissions. Delete it once the restore is done.

The rulesets surface spans more than WAF. The WAF permissions above cover your security rulesets; if your account also keeps other ruleset-based configuration, such as transform rules or configuration rules, grant the edit permission for those ruleset products too, since the engine re-applies each changed ruleset by its own id.

A dry run is different: it only reads your live config to compute the diff and writes nothing, so a read-scoped token is enough to preview a config restore. The Edit scopes above are needed only for the apply. The single console field is labelled an edit token because the apply is what it is there for.

How backup works

A cf-config run produces one signed, encrypted record per in-scope surface, written through the same unchanged seal pipeline as every other source, so a config snapshot carries the same integrity guarantees as your data backups.

The backup is fail-open per surface. A surface the discovery token cannot read, because of a missing scope, a deprecated endpoint, or an endpoint that refuses the token’s kind as page rules does, becomes an explicit unavailable marker rather than failing the whole snapshot. A surface that a run reads and finds not on your plan also becomes a marker, flagged as plan-gated.

In Auto mode the daily discovery finds unused and plan-gated surfaces before the run, so the run does not read them and they get no record of their own. From engine 0.3.6, the run’s coverage record names each of them with its reason. The archive stays complete, with one record per attempted surface, and it distinguishes “unavailable, and why” from an empty surface. Only if every attempted surface fails does the run fail loudly, because that means a broken token or the wrong account, not a per-surface gap.

List-shaped surfaces are paginated to exhaustion, so a zone with thousands of DNS records or firewall rules is captured in full rather than truncated at the first page. There is a hard ceiling on pages followed, so a buggy endpoint can never spin forever. If a surface still has more pages at that ceiling, the backup does not silently drop the tail: it records a visible truncated marker carrying how many pages and records it did read, and logs it. Each surface also has a per-surface buffered-size cap of 64 MiB, far above any realistic config surface; a surface whose serialised JSON exceeds it is marked unavailable rather than risking the Worker’s memory.

The three restore tiers

Every surface in the registry carries a restore tier that describes how it can be restored. The tier is shown in the restore plan so you see, per surface, whether an apply re-applies it for you or hands you a checklist. The split across the registry is idempotent 176, ordered 76 and re-provision 61.

Which surfaces auto-restore

Auto-restore in-band means the engine re-applies the surface straight back into your live account, through the console, as part of a restore apply. That is 60 of the 313 surfaces, and they are the idempotent surfaces that have a diff-driven write function.

By family, they span these parts of Cloudflare:

DNS and core, 13. DNS records, DNS settings, zone settings, managed transform headers, URL normalisation, account DNS settings, secondary DNS ACLs, and six single zone settings that Cloudflare exposes only at their own endpoints and omits from the aggregate settings response: automatic origin TLS key exchange, fonts, origin maximum HTTP version, origin TLS compliance, Speed Brain and automatic SSL mode.

Security and WAF, 8. Zone rulesets and WAF, page rules, firewall access rules, Zone Lockdown rules, User Agent Blocking rules, Page Shield settings, Leaked Credential Checks status and Bot Management.

Zero Trust, 13. Access tags, Gateway lists, Gateway configuration, Gateway logging settings, Zero Trust device settings, Zero Trust connectivity settings, device managed networks, device IP profiles, the global WARP resilience override, the WARP device policy, DLP email rules, tunnel virtual networks and the zone Zero Trust organisation.

Account settings and rules, 6. Account rulesets and WAF, account rule lists (the named IP and ASN lists that WAF and Gateway rules reference), account firewall access rules, Workers account settings, and both the account and zone custom page assets.

Everything else, 20. Email routing, its catch-all rule and the DMARC report configuration; Workers Observability saved queries; Universal SSL, Origin TLS client auth and cache origin post-quantum encryption; the Zero Trust organisation and Access key configuration; Certificate Transparency alerting; the zone RUM toggle, Smart Tiered Cache, Smart Shield and Zaraz configuration; Magic Network Monitoring rules, Magic BGP settings and Magic BGP filter profiles; AI Gateway gateways and AI Search namespaces; and KV namespace configuration, meaning the namespace itself and its title, not its contents.

One of the 60 carries a precondition on your discovery token. Page rules re-apply in-band only when the discovery token is a Cloudflare user token, because Cloudflare refuses the page rules endpoint to an account token by its kind and no permission changes that. An account-owned discovery token therefore captures 59 of the 60 and never captures page rules, so there is nothing to restore for that surface. Which kind of token you hold, and how to check covers the test and the remedy. No other in-band surface is affected by the token kind.

For the per-surface inventory, with each surface’s scope and restore tier and an explicit not-captured list, read the config surface reference. That table lists the same surfaces the backup adapter and the restore sink use, so it is the list to check a specific surface against.

A further 25 surfaces carry a write path that is not in that 60. Those writers were generated from Cloudflare’s published schema. The schema fixes the endpoint and method but not which field identifies an item, and that decides whether a restore writes to the right object. They are off by default, so a restore that does not name a scope will not touch them. Naming one puts it in the plan hash, so with restore approval on an approver sees exactly which off-by-default surface they are authorising.

228 surfaces are backup-and-preview only. They are captured in full and verified recoverable, and you re-apply them out of band: ordered surfaces re-created in dependency order, and re-provision surfaces rebuilt from their checklist, both from the verified snapshot. None of the 228 carry a diff preview against live, because none of them carry a write path for the engine to run in dry-run mode.

The 25 off-by-default surfaces do produce a diff when a request names one. They are the only surfaces outside the in-band 60 that produce one at all. The console is explicit about the default: it offers in-band re-apply for DNS, page rules, rulesets and firewall, and says that other configuration stays out of band for deliberate re-provisioning. The page rules half of that offer depends on the discovery token being a user token rather than an account token, since an account token cannot read the surface at backup time and so has nothing to re-apply.

The restore workflow and its guarantees

A cf-config restore rides the same restore path as a data restore: the same dry-run default, the optional dual-control gate and the additive discipline. Dual control is off until an owner turns on restore approval. The request and approval steps below apply only then; with it off, the apply proceeds on your own identity. You opt into the cf-config part by supplying an edit token and the account (and zone for zone-scoped surfaces) in the restore request; leave them blank and config records stay out of band exactly as a data-only restore would treat them.

1. Build the dry-run plan

   The dry-run is the default and writes nothing. For each in-band surface in scope, the engine reads your current live config and diffs it against the verified snapshot, then returns a per-surface summary of what an apply would change, for example “2 to add, 1 to change”, with any live-only items reported as left in place. A read or diff that fails for one surface is reported out of band with a coarse reason rather than failing the plan.

2. Raise a request

   When restore approval is on, a requester with the request capability raises a restore request bound to the plan. The engine recomputes the plan hash server-side, binding the run, the selectors and the cf-config account and zone, but never the token. A changed plan yields a different hash and re-arms the gate.

3. A distinct approver signs it

   A second authorised person with the approve capability approves that exact plan hash. The approver must differ from the requester on stable identity, the engine refuses a self-approval, and the approval is single-use with a 24-hour life counted from the dry run it was raised against. With restore approval on, holding the apply role is not enough on its own.

4. Apply

   Have your authenticator to hand for this step. Confirming the apply demands a fresh passkey assertion: the engine’s step-up gate reads the request’s own confirm flag, so the dry run passes freely and the write does not. It is checked after the role gate and before anything is reserved or written, so an unfresh apply is refused before any byte lands. A caller on the break-glass token is exempt. A Cloudflare Access session passes only while its Access sign-in is less than five minutes old; after that, the engine asks it to sign in to Access again.

   Once the approval gate passes, the apply re-verifies every record’s plaintext hash before any write, then re-applies each in-band surface to your live account with the edit token, additively. A surface write that fails is recorded as a per-surface failure so the result reflects it, never a silent drop.

The step-up is worth planning around rather than meeting by surprise. When restore approval is on, the approver step in front of it routinely takes longer than the freshness window the engine allows. Get the approval first, then re-authenticate, then apply, rather than re-authenticating and waiting on an approver.

The additive guarantee is the main safety property. An in-band apply creates or updates only the items that differ, one at a time, so one item the Cloudflare API rejects skips itself rather than failing the rest. It never replaces a whole collection, and it never deletes a live item the snapshot omits. A re-run converges: items that already match are skipped, and matching by a natural key rather than only by server id means a re-run does not duplicate.

Two refusals bound the path further. A truncated or unavailable snapshot is refused for restore, so a partial backup is never diffed or written against live config. And in the strict break-glass-only posture, where the engine holds no in-account read-back key, the console still restores: your browser supplies the break-glass key locally to open the one run you are restoring, and only a 32-byte per-run master, never the break-glass private key itself, reaches the engine. Only when neither an operational key nor a browser-supplied master is available does a restore return not-ok and write nothing, leaving offline recovery as fallback.

Related

• Dual control is the full mechanic behind the optional request and approve gate in front of a config apply.
• What restore can and cannot write back covers the same tiered and out-of-band split across all source types.
• The restore flow walks the end-to-end path from picking a run to the receipt.
• Roles and capabilities defines the request, approve and apply capabilities and which role holds each.
• Sources overview places cf-config alongside the data sources and the Workers source.

Last updated 25 September 2026.