How to Create a Custom Cloudflare API Token (2026 Guide)

#cloudflare #security #api #tutorial

Cloudflare's template tokens (Edit zone DNS, Workers AI, etc.) are the fastest path, but most of them are over-permissioned. A leaked token with too many scopes causes a lot more damage than one that can only do exactly what your app needs.

This guide shows the generic Custom Token flow that works for any resource — R2 uploads, DNS automation, Workers deployments, cache purging, and more. We'll cover the minimum-permission mapping for the most common use cases in Step 04.

Step 01 — Click 'Create Token' on the API Tokens page

Start here: dash.cloudflare.com/profile/api-tokens

From the Cloudflare dashboard, click the profile icon in the top-right to land on this page, then click the + Create Token button in the top right.

[!TIP]
User API Tokens vs. Account API Tokens: tokens created on this screen are scoped to your user. For CI/CD or shared team services, Cloudflare recommends Account API Tokens (created from the account-level admin area) so the token survives a person leaving. For personal automation scripts, user tokens are simpler.

Step 02 — Click 'Get started' under Custom token

On the template selection page, click Get started next to Create Custom Token at the top. Everything below is a preconfigured template, but templates are usually broader than what you actually need.

Step 03 — Enter a token name

Give the token a name that tells future-you where it's used. When a token starts misbehaving months from now, the name is the only cue in the token list and in audit logs.

Recommended naming pattern: {project}-{purpose}-{environment}. Examples:

myapp-r2-uploader-prod
myapp-dns-updater-dev
cicd-workers-deploy

Step 04 — Choose permissions (scope → resource → level)

Permissions are built from three dropdowns:

Scope — Account, Zone, or User
Resource — e.g. Workers R2 Storage, Zone DNS, Cloudflare Workers Scripts
Level — Read or Edit

Minimum permissions by use case:

Use case	Scope	Resource	Level
Upload to an R2 bucket	Account	Workers R2 Storage	Edit
Automate DNS records	Zone	DNS	Edit
Deploy Workers (wrangler)	Account	Cloudflare Workers Scripts	Edit
Purge cache only	Zone	Cache Purge	Edit
Read analytics	Account	Account Analytics	Read

[!TIP]
+ Add more lets you stack multiple rows, but stuffing many purposes into one token makes rotation painful. One token, one purpose is usually the right default.

The sections below — Account Resources / Zone Resources / Client IP Address Filtering / TTL — are worth restricting too. If your deploy server has a static IP, Client IP Address Filtering dramatically limits the blast radius if the token ever leaks.

Step 05 — Click 'Continue to summary'

Once permissions are set, click Continue to summary at the bottom of the page to review.

On the review page, clicking the final Create Token button displays the token string exactly once. Closing that screen loses the token forever.

[!WARNING]
Copy the token immediately to a safe place. A password vault (1Password, Bitwarden) or your CI secrets manager is the right destination. If you suspect a leak, roll it right away from the token list page — the ... menu has a Roll option.

Common mistakes

Picking a template because it's "faster": most templates are over-permissioned. Edit zone DNS grants zone-wide DNS write for a token that's supposed to do R2. Custom feels slow the first time, but it's faster in the long run.
Closing the final screen without copying: the only recovery is to recreate the token.
Leaving TTL at No expiration: the default is unlimited. Set an End Date at creation time or put a quarterly rotation reminder on your calendar.
Leaving IP filtering on while testing locally: your home/café IP changes. Use IP filtering only for deploy environments and keep a separate token for local use.
Sharing one token across teammates: you lose per-person audit trails. Each person issues their own, or set up a service account with its own token.