Cloudflare API tokens security guide: Scoping, Account Tokens, Rotation and Leak Response

A Cloudflare API credential can rewrite DNS, disable WAF rules, deploy Workers code or open a tunnel, so a leaked token is a change-control failure at the edge of every site it reaches. Cloudflare now issues several kinds of credential (user API tokens, account API tokens, the legacy Global API Key, the deprecated Origin CA key and Wrangler OAuth tokens), and they differ sharply in scope, ownership and what happens when the person who made them leaves. This guide goes deeper than the token section of the Cloudflare Security Configuration Guide: it covers token policy design, account-owned tokens for automation, IP and TTL restrictions, rotation, audit logging and leak response. It is for platform, DNS and secrets teams running Cloudflare through Terraform, CI or scripts. Facts are taken from Cloudflare's developer documentation as checked on 28 October 2026.

Key takeaways

• Know which credential you are holding. New Global API Keys start cfk_, user API tokens cfut_, account API tokens cfat_ and Wrangler OAuth tokens cfoat_, so scanners and responders can tell them apart at a glance.
• Retire the Global API Key. It carries every permission of its user across every account and zone, there is only one per user, and it cannot be restricted by IP or time.
• Use account API tokens for automation. They act as a service principal owned by the account, so CI and SIEM integrations keep working after an engineer leaves and audit logs show them as actor_type="account".
• Every token gets four limits. Smallest permission group, named resources, a client IP filter where egress is fixed, and an expiry date: by default tokens never expire.
• Treat token-creating tokens as privileged access. A token made from the "Create additional tokens" template can mint tokens with access to any of the user's resources.

How identity and access work for the Cloudflare API

Cloudflare separates users (people who log in), accounts (the billing and administration boundary that holds members, zones and products) and zones (domains). API credentials attach to one of the first two. A user API token acts on behalf of its user and holds a subset of that user's permissions. An account API token belongs to the account itself and acts as a service principal with its own permissions; Cloudflare positions it for CI/CD and for integrations such as SIEM feeds that must keep working after the person who configured them has left.

Tokens created before the scannable formats appeared in 2026 are unprefixed (40-character alphanumeric for both token types, 37 to 45 lowercase hex characters for a Global API Key) and still work, so a scanner tuned only for the prefixes will miss older credentials. Cloudflare's documentation lists the Origin CA key as deprecated with removal scheduled for 30 September 2026; check the API deprecations page for its current state and confirm nothing in your estate still sends the X-AUTH-USER-SERVICE-KEY header. Changing that key is not recorded in audit logs, and every view shows a different value, all valid until the key is changed.

Admin roles and who can mint tokens

Any user can create user API tokens for their own resources, so the control point for those is the member's own role. Account API tokens need the API Token Provisioning role or Super Administrator status. Super Administrators see and manage every account API token; other provisioners see only the tokens they created. A member can only grant an account token permissions that are a subset of their own, so a narrowly scoped provisioner cannot create a token more powerful than themselves.

• Keep Super Administrator small: it manages all account-owned tokens, members and billing; two or three named people with phishing-resistant MFA.
• Grant API Token Provisioning to a platform group: not to every engineer. Use member scoping so a provisioner's own permissions, and therefore their tokens' maximum reach, cover only the zones they look after.
• Use Enterprise API access controls: Super Administrators on Enterprise plans can disable API access for the whole account or for named members under Members, Enable API Access. Member settings override the account default, so an account-wide "off" with a few named exceptions is possible.
• Guard the token-creating token: the User, API Tokens, Edit permission exists only in the "Create additional tokens" template. Cloudflare recommends giving that token no other permissions and limiting it by IP or TTL, because it can create tokens with access to any of the user's resources.

For the role model beyond tokens, see the Cloudflare Security Configuration Guide.

Designing a least-privilege token policy

A token is a set of policies. Each policy has an effect (allow or deny), a set of resources and a set of permission_groups. Cloudflare evaluates explicit deny policies first, then explicit allow, then an implicit deny of everything else, so a deny policy is a reliable way to carve out a sensitive zone from a broad grant. Permission groups come in Read and Edit variants; Edit means full create, read, update, delete and list.

• Start from a template, then cut: templates such as "Edit zone DNS" prefill permissions; remove what the job does not call and use Read where it only reads. One token per integration and environment.
• Use permission group IDs in code: the name is cosmetic and may change. List IDs with GET /user/tokens/permission_groups or, for account tokens, GET /accounts/{account_id}/tokens/permission_groups (is_selectable shows what you may grant).

Restricting where and when a token works

Two runtime restrictions apply to API tokens, and the defaults are open: any IP address may use a token, and a token never expires unless you set an end date.

• Client IP address filtering: an Is in rule (condition, request.ip, in in the API) limits use to CIDR ranges; Is not in carves out exceptions. Fit it to self-hosted runners, NAT gateways and bastion ranges. Note that the filter is not applied to the Verify Token endpoint, so a successful verify call does not prove the IP rule works: test with a real API call from outside the range.
• TTL: not_before and expires_on bound the token's life. Dates set in the dashboard take effect at 00:00 UTC of the chosen day; use the API for finer times. Set an end date on every token for a project, migration or contractor.
• Hosted CI with changing egress: compensate with a short expiry and narrow scope.

Integrations, CI pipelines and secrets storage

Terraform, Wrangler deployments and scheduled jobs are non-human identities that each need an owner, a purpose and an expiry.

• Terraform and IaC: use an account API token, check the account token compatibility matrix for every product the configuration touches (at the time of checking, Page Rules, Registrar, Turnstile, Super Bot Fight Mode, Intel Data Platform and Zero Trust Client Platform were listed as not yet supported), and keep a user token only where a product requires it. See the Terraform and IaC Pipeline Credential Security Guide.
• Wrangler in CI: supply a scoped API token through the pipeline's secret store rather than copying a developer's cfoat_ OAuth token obtained with wrangler auth token. That OAuth token belongs to a person and refreshes itself, which is the opposite of what a pipeline credential should do.
• Store once: the secret is shown at creation only; write it straight to a secrets manager, never a ticket, wiki or chat.
• Verify before cut-over: call GET /client/v4/user/tokens/verify with the new token; a healthy response returns the token id and status: active. Record that id against the integration in your inventory.

The general lifecycle model (inventory, owner, rotation interval, revocation) is in the API Key Management Guide and the SaaS API Token Security Guide.

Rotation and migration off the Global API Key

Rolling a token in the dashboard (My Profile, API Tokens, then the three-dot menu, Roll) issues a new secret with the same permissions and invalidates the old one immediately, so roll only when the consumer can take the new value at once. For zero-downtime rotation, create a second token with the same policy, deploy it, verify, then delete the first. Rolling also moves legacy tokens to the scannable format.

1. Inventory: list user tokens for each automation account and account tokens under Manage Account, API Tokens. Pull 30 to 90 days of audit logs and group by authentication method; entries showing api_key are Global API Key use and origin_ca_key entries are Origin CA key use.
2. Map each consumer: the endpoints each Global API Key caller uses become its replacement token's policy.
3. Create replacements: one account API token per integration where compatible, with IP filter and end date. Test against the real endpoints in staging.
4. Cut over in rings: non-production, then low-risk production, then DNS and security automation, keeping the old credential for a dated fallback window.
5. Change the Global API Key: once audit logs show no api_key use for a full cycle of scheduled jobs, change the key so any forgotten copy stops working. Rollback during the window is simply re-pointing the consumer at the old credential.
6. Repeat: rotate on every owner change and review unused tokens quarterly.

Logging and detection

Audit Logs v2 records user-initiated and system-initiated actions across the dashboard and API, covering about 95 per cent of products per Cloudflare. Logs are kept for 18 months; the dashboard queries the last 90 days, and the API (GET /accounts/{account_id}/logs/audit, which needs Account Settings Read or Write) or Logpush reaches the rest. Each entry records the actor type (user, account for account API tokens, cloudflare_admin, delegated_service, system), the authentication context (api_token, api_key, oauth, origin_ca_key, dash), token ID and name where a token was used, and a Ray ID.

Metrics: Global API Keys in use (target zero); share of tokens with an end date; share of automation on account tokens; tokens unused for 90 days; median leak-to-revocation time.

Leak response

Cloudflare takes part in GitHub secret scanning. For public repositories GitHub verifies the token checksum and notifies Cloudflare, which revokes the token automatically and emails the owner; for private repositories GitHub alerts you and you rotate. Cloudflare also scans for leaked tokens in the old formats. Automatic revocation stops further use but does not undo what happened before it, so always work the full sequence:

1. Contain: roll or delete the token (or change the Global API Key) and deploy the replacement to the legitimate consumer.
2. Scope the exposure: query audit logs by the token ID for the full period since the secret was exposed, not only since the alert.
3. Revert: compare DNS, rules, Workers, tunnels and member lists against IaC state and undo unplanned changes.
4. Check for persistence: look for new tokens, members, Access service tokens and tunnels created in the window.
5. If an account login is suspected: follow Cloudflare's compromised-account steps: change the password, revoke active sessions, enforce two-factor authentication, change keys and tokens, review the audit log.

The Cloudflare Thanksgiving Breach 2023 is the lesson for the rotation step: after the Okta support system breach, Cloudflare rotated thousands of credentials but skipped one service token and three service accounts it wrongly believed were unused, and the attacker used them. Rotate everything in scope, and check use from logs rather than memory. See the Leaked Credential Response Playbook.

Framework mapping

Common misconfigurations

• Global API Key in Terraform or CI: one leak exposes every account the user belongs to, and there is no second key to rotate to.
• Automation on an engineer's user token: the pipeline breaks or, worse, keeps working through a departed person's identity.
• Prefix-only scanning: pre-2026 unprefixed tokens slip through detection rules written only for cfut_ and cfat_.

Practitioner checklist

• Inventory all user tokens, account tokens, Global API Keys and Origin CA keys, each with an owner and purpose.
• Move CI, Terraform and SIEM integrations to account API tokens where the compatibility matrix allows.
• Give every token named zones, the smallest permission groups and an end date.
• Add client IP filters for fixed-egress runners and test them with a real API call.
• Restrict API Token Provisioning and Super Administrator to small named groups.
• Find and eliminate api_key and origin_ca_key authentications in audit logs.
• Stream Audit Logs v2 to the SIEM and alert on token creation, permission changes and Global API Key use.
• Enable secret scanning for both prefixed and legacy token patterns in repositories and CI logs.

Standards and references

• Cloudflare: Create API token
• Cloudflare: Account API tokens
• Cloudflare: API token formats and leaked token detection
• Cloudflare: Create tokens via API
• Cloudflare: Restrict token use
• Cloudflare: Global API key
• Cloudflare: Audit Logs v2
• NIST: SP 800-53 Rev. 5 Security and Privacy Controls

Related NHI Mgmt Group resources: Cloudflare Security Configuration Guide, API Key Management Guide, Terraform and IaC Pipeline Credential Security Guide, Git Secret Scanning Guide, Leaked Credential Response Playbook.