How to create a Cloudflare API token to purge cache

A Cloudflare API token that can purge cache needs exactly two permissions: Zone → Zone → Read, to list your zones, and Zone → Cache Purge → Purge, to clear them. Create it at dash.cloudflare.com under My Profile → API Tokens → Create Token, using the Custom token template.

Cloudflare gives you two ways to authenticate against its API, and only one of them is a good idea. This guide covers the good one: a scoped API token that can do exactly two things and nothing else.

The two permissions you need

Purging cache through the API touches two endpoints, so the token needs two permissions:

Permission	What it allows	Required?
`Zone → Zone → Read`	List the zones in your account, with their names and IDs	Yes
`Zone → Cache Purge → Purge`	Clear cached content for those zones	Yes
`Account → Account Settings → Read`	Read account names, so zones can be grouped by account	Optional

That is the whole list. A purge token has no business reading your DNS records, editing firewall rules or touching SSL settings — and if it is ever leaked, the worst anyone can do with it is clear your cache.

Creating the token, step by step

Sign in at dash.cloudflare.com.
Open the profile menu in the top right and pick My Profile, then the API Tokens tab. The direct link is dash.cloudflare.com/profile/api-tokens.
Click Create Token, scroll past the templates and choose Create Custom Token.
Give it a name you will recognise in six months. FlarePurge — iPhone beats token 3: one token per device makes it trivial to revoke just the one that was lost.
Under Permissions, add Zone · Zone · Read and then Zone · Cache Purge · Purge.
Under Zone Resources, choose which zones the token can reach. All zones is the convenient option; Specific zone is the careful one.
Leave Client IP Address Filtering empty unless you have a fixed IP. A phone changes network constantly and an IP filter will lock you out.
Set a TTL if you want the token to expire on its own. Useful for a contractor, unnecessary for your own device.
Click Continue to summary, check that it reads exactly the two permissions above, and confirm with Create Token.

Why not the Global API Key

The Global API Key is the old authentication method: an email address plus a single key that grants full administrative access to every zone and every setting in your account. It cannot be scoped, and it cannot be limited to one operation.

An app that asks for your Global API Key is asking for the keys to your DNS, your firewall, your SSL configuration and your billing — in order to press a button that clears a cache. FlarePurge does not accept it, on purpose. If a tool insists on it, that tells you something about the tool.

Checking the token works

You can verify a token from any terminal before pasting it anywhere. Cloudflare has an endpoint for exactly this:

curl -s https://api.cloudflare.com/client/v4/user/tokens/verify \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" | jq

A healthy token replies with "status": "active". If you get Invalid API Token, the token was copied incompletely — that is by far the most common cause, because the value is long and easy to truncate.

To confirm the permissions are the right ones rather than merely valid, list your zones:

curl -s "https://api.cloudflare.com/client/v4/zones?per_page=5" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" | jq '.result[].name'

If that returns your domains, Zone:Read is in place. If it returns an empty list with success: true, the token is valid but its Zone Resources do not include any zone — go back and widen the scope.

Where the token should live

A purge token is a credential, and it should be stored like one. FlarePurge keeps it in the operating system's secure store — Keychain on Apple platforms, the Android Keystore, the Windows credential store — never in a plain text file or a preferences plist.

One token per device. If a laptop is stolen, you revoke one token instead of re-issuing every one you own.
Revoke, don't rotate in place. Deleting a token in the dashboard is instant and cannot be undone by whoever holds a copy.
Do not paste it into a chat or an issue tracker. Screenshots of the dashboard are also a leak: the token is visible in the creation screen.
Check the audit log. Cloudflare records token use under Manage Account → Audit Log, so unexpected purges are visible.

With the token created, the next decision is which kind of purge to run. Clearing everything is quick and blunt; clearing specific URLs is precise and slower to set up — the comparison is here. If you are hitting limits on large purges, see the API limits.