Cloudflare API tokens: least privilege and the token lifecycle
Guide Cloudflare API tokens: least privilege and the token lifecycle: # API tokens: permissions and lifecycle API tokens are the preferred auth for the Cloudflare API: each token carries a precise set of permissions instead of the all-powerful global API key. Use this when you hit exactly this in Cloudflare API tokens. Not for different errors or different tools.
TL;DR: # API tokens: permissions and lifecycle API tokens are the preferred auth for the Cloudflare API: each token carries a precise set of permissions instead of the all-powerful global API key. The token create page documents which operations each permission grants; check the required permission before debugging a 403, because the most common "API is broken" report is a token missing one permission. ## Permission scoping - Zone-scoped permissions (e.g.
API tokens: permissions and lifecycle
API tokens are the preferred auth for the Cloudflare API: each token carries a precise set of permissions instead of the all-powerful global API key. The token create page documents which operations each permission grants; check the required permission before debugging a 403, because the most common "API is broken" report is a token missing one permission.
Permission scoping
- Zone-scoped permissions (e.g. Workers Routes Write) act on specific zones. A Workers route change failing with a permission error usually means the token has Account scope but not the zone scope, or vice versa.
- Account-scoped permissions act across the account.
- Templates (e.g. "Edit Cloudflare Workers") bundle common permissions but are broader than a hand-picked set. Fine for humans, avoid for automation.
The lifecycle gotcha
- User tokens belong to a user and inherit their lifecycle: offboard the user (or rotate their credentials) and every integration using their tokens breaks.
- Account-owned tokens survive user changes and are the right choice for durable CI/CD and automation.
Checklist
- One token per integration, minimal permissions, named by purpose ("ci-deploy-zone-x").
- Prefer account-owned tokens for anything automated.
- Rotate on a schedule, and test the rotation (a rotation that breaks deploys at 2am is not a rotation, it is an incident waiting to happen).
- Never use the Global API key where a token works; the key cannot be scoped.
When to use
You hit exactly this: Cloudflare API tokens: least privilege and the token lifecycle in Cloudflare API tokens.
When not to use
A different error, or the same symptom in a different tool. This page only covers the failure above.
Compatibility
Cloudflare API tokens.