Cloudflare API Token

Quick reference

• Env var: CLOUDFLARE_API_TOKEN
• Required for: every deploy (uploads workers, writes secrets, sets up custom domains)
• Permissions / scopes: all of the following must be present — getting any one wrong is the #1 cause of failed deploys.
  • Account → Workers Scripts → Edit (write workers)
  • Account → Account Settings → Read (verify account access)
  • Account → Workers KV Storage → Edit (auth service KV namespace)
  • Zone → DNS → Edit (only if using a custom domain — skip if you're deploying to *.workers.dev)
  • Zone → Zone → Read (only if using a custom domain)
  • Zone → SSL and Certificates → Edit (only if using nested subdomain DNS style — see mastrakit.config.json → domainStyle: "nested")
• Validation: mastrakit doctor --key CLOUDFLARE_API_TOKEN — calls GET /user/tokens/verify, then introspects the permissions list and reports specifically which ones are missing.

Create one

Use a Custom Token, not "Edit Cloudflare Workers". The pre-built "Edit Cloudflare Workers" template is too narrow — it can't write DNS records or KV namespaces. You'll get a misleading "Authentication error" partway through deploy.

1. Go to dash.cloudflare.com/profile/api-tokens.
2. Click Create Token.
3. Scroll to the bottom and click Get started under Create Custom Token.
4. Token name: mastrakit-<your-slug>-deploy (any name, just for your reference).
5. Permissions — add each row below:

   Type	Resource	Action
   Account	Workers Scripts	Edit
   Account	Account Settings	Read
   Account	Workers KV Storage	Edit
   Zone	DNS	Edit (custom domain only)
   Zone	Zone	Read (custom domain only)
   Zone	SSL and Certificates	Edit (nested-subdomain only)

6. Account Resources — Include → <your account name>. Don't leave it as "All accounts" — scope it down.
7. Zone Resources — Include → <your domain> (if using custom domain). Otherwise skip.
8. TTL — leave blank for no expiry, or set 1 year for hygiene.
9. Click Continue to summary → Create Token.
10. Copy the token. You can only view it once.

Add to your project

Paste into .env.dev-secrets (gitignored):

CLOUDFLARE_API_TOKEN=<paste>

Common validation failures

The validator introspects the token's permissions and reports specifically what's missing. Example failure messages:

• ❌ missing permission: com.cloudflare.api.account.worker.script.write — Add Workers Scripts: Edit to the token.
• ❌ missing permission: com.cloudflare.edge.dns.write — Add DNS: Edit for the zone. Only needed if you're deploying to a custom domain.
• ❌ missing permission: com.cloudflare.api.account.zone.ssl-cert.write — Add SSL and Certificates: Edit. Only needed if your mastrakit.config.json has domainStyle: "nested" (using Cloudflare Advanced Certificate Manager).
• ❌ token does not have access to account <id> — Token's Account Resources don't include the account from your CF_ACCOUNT_ID. Edit the token or re-copy the right CF_ACCOUNT_ID.
• ❌ 401 invalid api token — Token was revoked, expired, or pasted wrong. Re-create.

To fix: re-edit the token at dash.cloudflare.com/profile/api-tokens → click the token name → Edit → add the missing permission → Continue to summary → Save. You don't need to create a new token; the existing key keeps working.

Why so many permissions?

Each one corresponds to a specific deploy step:

• Workers Scripts: Edit — wrangler deploy (every service)
• Workers KV Storage: Edit — Better Auth needs a KV namespace for rate-limit state
• DNS: Edit + Zone: Read — setting up auth-<slug>.<domain> custom domains
• SSL and Certificates: Edit — provisioning the ACM certificate for nested-subdomain style

A token with all six rights is needed for a full first-time deploy. After deploy you can rotate it to a narrower one if you want (only Workers Scripts: Edit is needed for re-deploys without DNS changes).