Cloudflare API tokens

Everything starts from one credential, and you no longer make it by hand: sign in to Cloudflare in your browser. Every other credential the project needs is minted from it, scoped to exactly what needs it. There are two: ci-system, which CI runs under, and runtime, which your deployed application runs under.

The bootstrap token

pithy token mints and rotates these, the config directory is where one lives on your machine, and a CI pipeline is the main reason to mint a narrower one.

Sign in: pithy cloudflare connect. It opens Cloudflare’s consent screen in your browser and keeps a session for the directory you ran it in. No token is made by hand, and wrangler login is not needed. The session asks for what this project’s tokens carry — ci-system and runtime, in every environment — and a small base: who you are, your account and its zones, renewal without a browser, and Account API Tokens Write, so it can mint them. Nothing a capability the project does not compose, or a resource it does not bind, would need.

Turn on Account API Tokens Write before you approve. Cloudflare lists it under “Sensitive scopes”, switched off, and without it the sign-in fails. Every audit row the CLI writes under a session names the person who signed in. Registering a dashboard connection takes one: pithy dashboard connect records that person as who authorized it, and refuses an account token. pithy cloudflare has the flow, including signing in over SSH.

Or set an account token, the one you create in the Cloudflare dashboard. It lives in <config>/cloudflare.json — account-scoped, mode 0600, outside every checkout, written by pithy init at the one moment you are already holding it. Or it arrives as environment variables, overlaying the file per key. CI has no browser, so CI always runs this way, under the ci-system token pithy token mint made for it. Audit rows written under an account token name the token, not a person.

A profile bound to a directory wins over the file and the environment there, and an exported credential that differs from its session is refused rather than preferred. pithy mints every other token from whichever credential resolves.

At minimum an account token needs API Tokens → Edit, at account scope, so the CLI can create, roll and delete account-owned tokens.

The delegation rule

Cloudflare only lets a token create another token whose permissions it already holds.

So the bootstrap token must itself hold every permission it will delegate: the union of what your composed capabilities need CI to do and what your deployed Workers call Cloudflare with, plus the token-editing permission above.

A session is held to the same rule, against the scopes it was granted. Compose a capability, or bind a resource, that needs a permission the session was not granted, and pithy token mint and pithy token rotate refuse before Cloudflare does, naming the missing permissions. pithy cloudflare connect asks for them, and you approve them.

Permission names are resolved against your account at mint time. An unknown or missing one fails loudly, never silently mis-scoped — which is the failure worth designing against, because a token that is quietly missing one permission works until the day it does not.

ci-system — the one CI credential

CI runs migrate and deploy in one process under one credential, so there is one token for it.

pithy token mint ci-system --env prod

Its permissions are the base — deploy Workers, migrate remote D1, read and write the Secrets Store — plus whatever the composed capabilities need CI to do, plus what every binding needs. You never hand-list them, and a permission added after the token was made takes effect on the next rotate, not the next mint. The binding half is read off the binding rather than declared, so a binding your own app declares counts exactly as a capability’s does. An r2 bucket brings R2 Write, a kv namespace brings KV Write and a vectorize index brings Vectorize Write, and each write covers its read. A queue brings Queues Write, and artifacts brings Artifacts Write. pithy provision creates the bucket, namespace or queue behind each binding, a capability’s provisioner creates its Vectorize index, and pithy feature destroy deletes every repository in a feature’s Artifacts namespace and then the namespace. runtime carries none of them. A Worker reaches each of these resources through its binding, and a binding needs no API token.

Your declared domains, and the route CI attaches

A Worker that declares domains answers on a custom domain, and deploying one is two calls, addressed to two different scopes — and only one of them needs a grant the account policy lacks:

CallEndpoint scopeGrant
GET/POST /zones/<zone>/workers/routes — wrangler reconciles the zone’s route listzoneWorkers Routes Write, on that zone
PUT /accounts/<id>/workers/domains — the custom domain itselfaccountNone beyond the account policy — Workers Scripts Write, already in ci-system’s base

This is measured, and it disagrees with Cloudflare’s own page. Workers roles and permissions says API tokens need Workers Routes Write, scoped to each affected zone, for routes and custom domains alike. The kit’s live suite watched a token carrying only the account policy attach a custom domain, and watched the same token refused on the zone’s route list — so the route call is the one the zone grant is for, and it is the call every deploy of a declared domain makes.

So one zone-scoped grant unblocks the deploy. A minted token’s resources are account-scoped, and the account policy every other permission rides on grants a zone-level group nothing at all — which is why every deploy of a declared domain failed.

So ci-system carries a second policy: Workers Routes Write, on exactly the zones your declared domains sit in, and not a group that can alter a zone. Only that route policy is zone-limited. The base grant is not: Workers Scripts Write attaches a custom domain on any zone in the account, which creates a proxied DNS record and a certificate for that hostname there — measured, in the table above. So ci-system can put a Worker on a hostname in any zone the account holds, declared or not. Keep it where you would keep a credential that can: in your CI’s secret store, readable only by the jobs that deploy. If the account holds zones this project has no business touching, give the project an account of its own: no token scope draws that line.

You declare nothing extra. The zones come from domains in each Worker’s pithy.config.ts, composed for the environment you are minting for, and resolved by name against your account at mint time. Two consequences worth knowing:

  • A zone that cannot be scoped fails the mint, naming what is wrong with it. Three ways: your account does not hold it, your account holds two of that name, or Cloudflare is not serving it yet — pending, initializing, moved. That is deliberate: a token minted over any of them passes every check here and fails in CI, hours later, with an error that names a zone id and nothing else.
  • The bootstrap token needs this grant too, by the delegation rule above: Workers Routes → Edit on those zones, alongside its account permissions. Cloudflare only lets a token create a token whose permissions it already holds, so without it the mint answers 403 — and the refusal says so by name.

A project that declares no domain mints exactly what it minted before. No new permission for a project that needs none.

An explicit --permission — or a tokens.overrides["ci-system"].permissions in pithy.config.ts — means exactly what it says. The route policy rides with the profile’s default permission set, not with every mint, so a run that narrows the credential by hand gets the narrow credential, with no zone grant added behind your back. A standing override keeps stripping the grant, on purpose: pithy token list reports that state as its own thing and tells you to change the override rather than to run a command that would honor it and produce the same token again.

A CI token minted before this carries no zone, and the next deploy of a custom domain fails on the route. pithy token list --env <env> says so and names the remedy. It reads the token’s own policies for the route grant and the zone, so a zone-scoped permission that is not a route grant does not count as coverage; a disabled or expired token is reported as dead rather than as scoped; and when the zones or the group cannot be read it says nothing rather than guessing, and never takes the listing down with it.

Inbound mail, and the rules CI makes

A capability that routes inbound mail through Cloudflare Email Routing declares the addresses its composition claims, and pithy support provision routes each one on the zone that holds its domain. Every call it makes there is zone-level:

CallGrant
GET /zones — find the zone holding the address’s domainZone Read (zone:read)
GET /zones/<zone>/email/routing and GET /zones/<zone>/email/routing/dns — check Email Routing is enabled for the domainZone Settings Read (zone-settings:read)
GET/POST/PUT/DELETE /zones/<zone>/email/routing/rules — read, create, update and remove the ruleEmail Routing Rules Write (email:routing)

So ci-system carries a third policy: those three, on exactly the zones holding the composition’s inbound addresses, found by the longest active zone name each address’s domain sits under, so a subdomain’s address grants its parent zone. An address no zone on the account holds grants nothing and does not fail the mint: provisioning refuses to route it and says why. A project that receives no mail gets no Email Routing grant, and mints exactly what it did before.

A signed-in session asks for the same three scopes whenever a composed capability routes inbound mail, because a session is not scoped by zone. pithy email routes its bounce rule from flags and declares no address, so ci-system holds no grant for that rule: make it from a session, or a token you scoped to that zone yourself. A ci-system token minted before a capability routed mail carries none of the three, and pithy token rotate is what adds them.

None of the three can change a zone, its DNS or its MX. Enabling Email Routing for a domain stays your act, in the Cloudflare dashboard.

Getting the value into CI

This is the one place a credential has to cross a gap by hand, and it is worth understanding why.

CI has no Pithy config directory, and neither secret store is readable from outside a Worker. So the flow is: mint the token, read its value out, and set it as your CI system’s own secret.

--store dev-vars (the default) writes the value to <config>/<project>/tokens.json, mode 0600, keyed by environment. Nothing in the CLI ever reads a credential out of that file. It is a handoff to a person: you open it, copy the value for the environment you minted, and paste it into your provider’s secrets.

Once CI has it, the local copy has no reader left. pithy token forget ci-system --env prod drops it and leaves the token live. It refuses while Cloudflare says nothing has ever used the token, because then this file may be its only copy. pithy token revoke drops the local copy too, since a deleted token’s value has no reason to stay.

--store ephemeral writes nothing at all — for a job that mints and uses a token in the same step.

Nothing was ever written into the checkout, for any environment. It used to be a per-environment file in the repo, which put a live production credential in a directory npm pack can reach.

runtime — the one token a deployed application holds

CI runs under one token. So does the application. A deployed application holds one Cloudflare API token, and no more. runtime is the credential every deployed Worker of an environment reads when it calls Cloudflare — the secrets manager rotating its key, media minting an upload or reading what it served, turnstile reading how its challenges went — and no capability can add a second.

Its permissions are composed, never listed. A capability declares what its Workers call Cloudflare with as runtimePermissions, the way it declares ciPermissions, and runtime carries the union, each key once. There is no field for a capability’s own token. A project composing nothing that declares runtime permissions mints no runtime token.

CapabilityruntimePermissionsWhat the Worker does with them
@pithy-sh/secretssecrets:read, secrets:writeThe manager’s at-rest rotation writes the new key set back to the Secrets Store
@pithy-sh/mediaimages:write while images are in Cloudflare Images, stream:write while video is in Stream, analytics:read while either isMints direct uploads, changes signing, deletes, and reads what was served. Both in R2: nothing
@pithy-sh/turnstileanalytics:readReads a real widget’s challenge outcomes, filtered by its sitekey. A test-key environment makes no call

One token per environment. runtime is minted into the Secrets Store at <project>-<env>-runtime-cf-api-token and bound as RUNTIME_CF_API_TOKEN into every Worker of that environment that calls Cloudflare — the secrets manager, the media host, and your app Worker. No human is in the loop. pithy secrets provision mints it for each environment, and pithy token mint runtime --env <env> writes the same entry under the same token name, so the two cannot leave an environment holding two. A feature’s Workers bind none: nothing mints one for a feature, so branch code never holds it.

pithy token mint runtime --env prod

One token is fewer credentials, not less privilege per Worker. runtime is the union, and every Worker it is bound into holds all of it. Compose secrets and media, and the manager holds Images, Stream and analytics grants it never calls, while the media host and your app Worker hold Secrets Store Write. That store is flat and account-wide: every environment’s entries live in it, production’s master key included. A compromised app Worker can rewrite any entry in it, so treat app Worker code as holding the manager’s authority. What the rule buys is one credential per environment to mint, rotate and revoke, and none built by hand.

It reads the whole account’s analytics, not one environment’s. analytics:read is Account Analytics Read, and that is Cloudflare’s grain. A capability narrows what it returns itself: media joins what was served to this environment’s own assets, so an account-wide dataset answers for this environment and nothing else. Turnstile filters its events by the sitekey in force for this environment, so it answers for that widget and no other.

  • The minter must hold every runtime permission too, by the delegation rule above. A session made before you composed media or turnstile cannot mint what they added: run pithy cloudflare connect again.
  • A token that already exists needs a rotate, not a mint. Compose media after runtime was minted for secrets alone, and the token lacks Images Write, Stream Write and Account Analytics Read. Compose turnstile after it, and the token lacks Account Analytics Read. pithy token list reports it as missing a grant and names the rotate. Until it is rotated, an analytics read on it answers media/analytics_forbidden or turnstile/analytics_forbidden, 409, naming Account Analytics Read and the rotate that adds it.

Upgrading to one token

Before runtime, an application held up to three: the secrets manager’s own token (<project>-global-secrets-manager, or <project>-<env>-secrets when minted with pithy token mint secrets), and the Images and Stream token pithy media provision stored in media-storage-credentials — the one you passed as --api-token, or your bootstrap token when you passed none. Both are superseded. Move without a gap, in this order:

  1. Mint runtime. pithy secrets provision mints it for every environment, and redeploys each manager to read it.
  2. Deploy your app Workers on this kit. pithy provision --env <env> binds runtime into them; then pithy deploy. The app moves before any bundle is rewritten, because a Worker on the old kit cannot read a bundle without its token.
  3. Rewrite the bundles. pithy media provision rewrites media-storage-credentials with the account id and nothing else, and media-r2-credentials without a token. pithy storage provision rewrites storage-r2-credentials the same way.
  4. Revoke the old tokens. Nothing is revoked for you. pithy token revoke secrets --env <env> removes a per-environment manager token. The global one is revoked in the Cloudflare dashboard, under Manage Account → Account API Tokens. Revoke the media token there too, but only if you made it for media: if you passed no --api-token, it is your bootstrap token, which you keep.

pithy token list --env <env> names each superseded token still present, and pithy doctor names each one once runtime is minted.

R2’s key pair is outside the rule. It is not a Cloudflare API token: Cloudflare offers no API to mint it, and it addresses one bucket over the S3 protocol. pithy storage provision and pithy media provision still take it, and the bundle that stores it holds no Cloudflare API token. A bundle written before the change also holds the R2 token the pair derives from. Re-run the provision to rewrite it, and keep that token: revoking the pair’s parent breaks the pair.

Token names are project-scoped

A minted token is named <project>-<env>-<profile>.

Cloudflare’s token list is account-wide and flat, so the project segment is what keeps two Pithy projects in one account from listing, rotating and revoking each other’s credentials. pithy token list filters its tokens on that prefix and shows no other token there. The one exception is its superseded list, which names this project’s old secrets manager token, <project>-global-secrets-manager, by its exact name, so an upgraded project can find it and revoke it.

The store entry a value is written to is scoped the same way. The variable name is not — CF_TOKEN_CI_SYSTEM and RUNTIME_CF_API_TOKEN stay as they are, because each is a variable key or a binding name rather than a name in a shared namespace.

Rotation is mint, store, then delete

Cloudflare has no single call for it, so pithy token rotate is the proven two-step: mint a new token under the same name with the profile’s current policies, store the value, then delete the tokens that predate it.

Mint rolls the value. Rotate replaces the token. The difference is the whole of it:

What it does to the token
pithy token mint <profile> --env <env>Same token, same id, same policies. A new secret, and nothing else changes
pithy token rotate <profile> --env <env>A new token with the profile’s current policies, stored, then the old one deleted

So a token that predates a permission — the zone route grant, a capability you have since composed, or a resource the project now binds — is re-scoped by rotate. A mint hands you a fresh secret with the old scope and changes nothing about what it may do.

A mint over a token that is disabled or expired says so. The value it writes is real and the token is dead, so the command names the status and points at rotate rather than printing Done. over a credential that fails on its first call. --json carries the status too.

Mint deliberately does not re-scope. It briefly did, and Cloudflare’s token update is a full representation — so doing it meant every mint had to resend the whole token correctly, and a bug there silently cleared a hand-set expiry or IP allowlist, or re-enabled a token you had disabled. Rotate was always the operation that replaces a token; mint is the one you can rely on to change exactly one thing.

--keep-previous leaves the old one standing as a grace window while a Worker consumer picks up the new value. Redeploy first, then revoke.

pithy token revoke deletes every account token of the profile’s computed name for that environment — and the project segment in that name is what keeps the sweep inside your project. Then it drops that profile’s local copy from tokens.json, and a cleanup that cannot run is reported without failing the revoke.

No command ever prints a token value

Not on stdout, not in --json, not in an audit event, not in an error.

The value goes to the store the profile resolves, and the output says only which store, and where. That is a property to rely on rather than a habit: the payload has no field that could carry one.

Every mint, rotate and revoke, and every forget that drops a value or is refused, is audited when the project composes audit — carrying the token’s id or profile, never its value.

The account is resolved before the credentials are read

A project says which account it belongs to in its root config. That resolution happens first, before any credential file is opened.

Minting into a file the project did not select would create a real token in somebody else’s account — which is the failure that ordering prevents. A pinned account id that disagrees with the resolved credentials refuses before anything is spawned, naming both.

ESC