Skip to content
MailRizMailRizMailRiz

Cloudflare API token

The setup wizard needs an API token to build the stack in your account. It opens the token page for you with the name pre-filled, but you can create it beforehand.

Go to My Profile → API Tokens → Create Token → Create Custom Token in the Cloudflare dashboard.

Required scopes

Section titled “Required scopes”

Seven, and each is used for exactly one thing:

# Scope Used for
1 Account → Workers Scripts → Edit deploying the Worker
2 Account → D1 → Edit creating the database and applying migrations
3 Account → Workers R2 Storage → Edit creating the three buckets
4 Zone → Workers Routes → Edit attaching the dashboard’s custom domain
5 Zone → Email Routing Rules → Edit enabling routing and the catch-all
6 Zone → DNS → Edit the MX and SPF records Email Routing needs
7 Zone → Zone Settings → Edit reading and adjusting zone configuration

Optional scope

Section titled “Optional scope”
Scope Used for
Account → Access: Apps and Policies → Edit creating the Cloudflare Access application

Without it, setup detects that Access is unavailable before deploying anything and offers password authentication instead. You are not left with a half-built install — the choice is made up front.

Zone resources

Section titled “Zone resources”

Scope the token to the zone mail will arrive on. Account-level permissions apply to the account you pick during setup.

After setup

Section titled “After setup”

The token is only needed again for update and destroy. At the end of setup you are asked whether to save it; the default is no, because it can delete your Worker, database, and stored mail.

If you decline, export it when you need it:

Terminal window
export CLOUDFLARE_API_TOKEN=...
mailriz-cli update

Check whether one is stored with:

Terminal window
mailriz-cli status

It reports whether a token is on disk — never its value.

Rotating

Section titled “Rotating”

Create a new token, then either export it as $CLOUDFLARE_API_TOKEN or paste it at the prompt the next time a command asks. update, reconfigure and destroy all prefer what you type over what is saved, so a rotated token needs no other step.

If a revoked token is sitting in ~/.mailriz/config.json, commands fail with an authentication error. Run reconfigure and paste the new one to replace it.