Cloudflare OAuth vs API tokens

Same permissions, different ceremony

Both paths end in the same place. Flowmails needs to create a Worker, a D1 database, a KV namespace and an R2 bucket in your account; install one Email Routing catch-all per zone; and read your zone list. The set of permissions is identical, and it is the set walked through in our permissions walkthrough. Nothing was loosened to make sign-in possible.

What changed is who types it. The token path asks you to hand-craft nine permission groups in a dashboard form and then paste a 40-character secret into a web app. The OAuth path asks Cloudflare to show you its own consent screen listing the scopes, and you click approve. The token you receive never touches your clipboard, your password manager, or a chat window.

How long the sign-in lasts, precisely

Shorter than you are probably expecting. Cloudflare signs third-party OAuth clients with a short-lived access token — about an hour — and returns no refresh token. Its scope catalogue has no offline_access, so there is nothing to ask for: after roughly an hour the bearer is spent and the only cure is a fresh consent.

We do not paper over that. The grant is stored server-side with an expiry stamped into the record itself, capped to the token's own lifetime rather than to anything longer, and Cloudflare's key-value store deletes it when the window closes. Nothing depends on you remembering to revoke anything, or on us running a cleanup job — and nothing claims a duration longer than Cloudflare actually grants us.

When the window closes, your deployed workers keep running. Mail keeps flowing. What stops working is the next action that needs to reach into your account — deploying a worker, upgrading one, repairing a domain. At that point the dashboard offers you the same one-click sign-in again, and says plainly that it expired rather than claiming your credential was invalid.

What it does not do

Two claims are worth retracting before you assume them.

• It is not a refresh token. Some OAuth providers hand back a renewable credential so the user is never asked again. Flowmails deliberately discards Cloudflare sends none, and Flowmails discards one if a future version ever does. A stored refresh token would turn an hour-long credential into an indefinitely renewable one for anyone who ever read our key-value store — a strictly worse outcome for you than re-clicking a consent screen.
• It does not make the token path obsolete.If your security review needs a credential with a readable policy you can attach to a ticket, an OAuth grant cannot produce one: the whole point of it is that you never handle the secret. Use a token for audit, use sign-in for convenience.

The two are not mutually exclusive. Keep a token for the record and sign in when you want to ship something; the most recent of the two wins, and you can see which one is live at Settings → Cloudflare along with a countdown of how long it lasts.

Deleting something without credentials

One behaviour changed alongside sign-in and it is worth knowing about if you ever close a Cloudflare account.

Deleting a domain or a worker has two halves. Ours — removing the records from Flowmails and clearing the receive worker's routing table — needs no credential from you. Cloudflare's — removing the catch-all rule, the R2 custom hostname, the worker script — does. Flowmails used to treat a missing credential as a hard stop, which meant that if your token had expired you could not remove a domain from your own dashboard. That was backwards.

Now the delete completes and tells you precisely what was left behind and where to remove it by hand. The consequence it is most careful to state out loud: if the catch-all is still installed on Cloudflare, mail to that domain can keep arriving at the receive worker while being invisible in Flowmails. You get an explicit list, not a silent half-state.

Which should you use

• Sign in with Cloudflare if you are setting something up right now, want to be running in a minute, and would rather not have a long-lived secret sitting anywhere. Be honest about the trade: Cloudflare expires that sign-in in about an hour, so it suits a focused session rather than an ongoing relationship.
• An API token if you need an auditable permission list for a security review, if you deploy from somewhere unattended, if you come back to the dashboard more than an hour apart, or if you simply prefer to own the lifecycle of your credentials. For anything ongoing, this is the default answer.
• Either, then — they coexist, and the dashboard always shows which one the next deploy would use.