Doota involves two different Cloudflare tokens with different jobs. Don’t reuse one for the other:
| Token | Who uses it | When |
|---|---|---|
Deploy token (CLOUDFLARE_API_TOKEN) |
Alchemy / CI | Deploy time only — creates and updates Workers, database, storage, queues. Scopes are listed in Deploy. Local deploys don’t need it at all (browser sign-in). |
App runtime token (APP_CLOUDFLARE_API_TOKEN) |
The running web app | When an org onboards a mail domain. This page is about this token. |
The running app calls the Cloudflare API to onboard domains: create (or reuse) the zone, enable Email Routing, write MX / SPF / DKIM / DMARC records, and point the catch-all rule at the mail-in Worker. This is the only place the app touches the CF API — never on the inbound hot path or during login.
Create the token
Open the token page
In the Cloudflare dashboard: My Profile → API Tokens → Create Token → Create Custom Token.
Grant the permissions below
Add each permission at the scope noted. Restrict Zone Resources to the account (or specific zones) that will host Doota domains.
Store it as a secret
Copy the token once — it’s shown only at creation — and set it as
APP_CLOUDFLARE_API_TOKEN in your deploy environment (infra/.env
locally, a repository secret in CI), then redeploy — the deploy binds it
to the web Worker. Never commit it.
Required permissions
| Permission | Scope | Why |
|---|---|---|
| Zone → Zone → Edit | Account | Read zone status; needed to wire records. |
| Zone → DNS → Edit | Account | Write MX, SPF, DKIM, DMARC, return-path records. |
| Zone → Email Routing Rules → Edit | Account | Enable routing and set the catch-all rule. |
| Account → Email Routing Addresses → Edit | Account | Manage routing destinations. |
| Zone → Zone → Create | Account | Only if Doota should add brand-new domains not already on your account. |
The account ID
You also need your Account ID (APP_CLOUDFLARE_ACCOUNT_ID). Find it in the
dashboard on any domain’s Overview page (right sidebar) or under Workers &
Pages → Account details.
Rotation
Rotate the token if it may have leaked, and on a regular cadence for hygiene.
Create the replacement first, update the APP_CLOUDFLARE_API_TOKEN secret, then
revoke the old token — nothing on the mail hot path depends on it, so rotation
has no user-facing impact.