KaisouMail Docs
Home
Quick Start
Deployment
Cloudflare Token
Storybook
GitHub
Home
Quick Start
Deployment
Cloudflare Token
Storybook
GitHub

Cloudflare Token Permissions

Recommended production setup

Purpose Stored in Secret name Value
Runtime mailbox-domain management Cloudflare kaisoumail-api Worker secret CLOUDFLARE_RUNTIME_API_TOKEN runtime token
Deploy workflow GitHub repository secret CLOUDFLARE_DEPLOY_API_TOKEN deploy token

This repository already supports split tokens. No code change is required. Direct binding from /domains also requires the GitHub repository secret CLOUDFLARE_ACCOUNT_ID. The deploy workflow injects that value into the API Worker runtime variables; it is not a token permission, but without it /api/meta reports cloudflareDomainBindingEnabled=false.

Runtime token example

支持👤
← 返回以查看所有令牌
创建自定义令牌
正式环境 / runtime token
给 kaisoumail-api Worker 用，只负责域名目录和 Email Routing 管理。
令牌名称
为您的 API 令牌指定描述性名称。
cfm-runtime
权限
按 KaisouMail 对应场景把权限配全即可。
资源
权限
权限级别
区域▾
Zone▾
编辑▾
区域▾
Email Routing Rules▾
编辑▾
区域▾
Zone Settings▾
编辑▾
帐户资源
按这个示意选择范围即可。
包括▾
目标 Cloudflare 帐户▾
区域资源
推荐覆盖当前项目会管理到的所有目标区域。
包括▾
该帐户内所有 zones（含待新建 zone）▾
把这把 token 填到 Cloudflare Worker secret：CLOUDFLARE_RUNTIME_API_TOKEN。

Deploy token example

支持👤
← 返回以查看所有令牌
创建自定义令牌
正式环境 / deploy token
给 GitHub Actions 用，只负责部署、Pages 和远程 D1 migration。
令牌名称
为您的 API 令牌指定描述性名称。
cfm-deploy
权限
按 KaisouMail 对应场景把权限配全即可。
资源
权限
权限级别
帐户▾
D1▾
编辑▾
帐户▾
Workers 脚本▾
编辑▾
帐户▾
Workers R2 存储▾
编辑▾
帐户▾
Cloudflare Pages▾
编辑▾
区域▾
Workers Routes▾
编辑▾
帐户资源
按这个示意选择范围即可。
包括▾
目标 Cloudflare 帐户▾
区域资源
推荐覆盖当前项目会管理到的所有目标区域。
包括▾
用于 Worker Routes 的区域▾
把这把 token 填到 GitHub repository secret：CLOUDFLARE_DEPLOY_API_TOKEN。

Quickstart for a single operator

If you only need the fastest single-operator setup for evaluation or a low-risk environment, you can keep one shared token:

  • Cloudflare kaisoumail-api Worker secret: CLOUDFLARE_API_TOKEN
  • GitHub repository secret: CLOUDFLARE_API_TOKEN

That shared token must cover both runtime and deploy permissions.

支持👤
← 返回以查看所有令牌
创建自定义令牌
快速上手 / shared token
单人试用时可共用；同一把 token 同时给 Worker 和 GitHub Actions。
令牌名称
为您的 API 令牌指定描述性名称。
cfm
权限
按 KaisouMail 对应场景把权限配全即可。
资源
权限
权限级别
区域▾
Zone▾
编辑▾
区域▾
Email Routing Rules▾
编辑▾
区域▾
Zone Settings▾
编辑▾
帐户▾
D1▾
编辑▾
帐户▾
Workers 脚本▾
编辑▾
帐户▾
Workers R2 存储▾
编辑▾
帐户▾
Cloudflare Pages▾
编辑▾
区域▾
Workers Routes▾
编辑▾
帐户资源
按这个示意选择范围即可。
包括▾
目标 Cloudflare 帐户▾
区域资源
推荐覆盖当前项目会管理到的所有目标区域。
包括▾
该帐户内所有 zones（含待新建 zone）▾
把同一个 token 同时填到 Worker secret 和 GitHub repository secret：CLOUDFLARE_API_TOKEN。

Resolution order

Surface Preferred secret Fallback secret
API Worker runtime CLOUDFLARE_RUNTIME_API_TOKEN CLOUDFLARE_API_TOKEN
Deploy workflow CLOUDFLARE_DEPLOY_API_TOKEN CLOUDFLARE_API_TOKEN

If split-token secrets and a shared token both exist, the split-token secrets win.

Runtime token minimum permissions

Runtime code calls:

  • GET /zones
  • POST /zones
  • GET /zones/:zone_id
  • DELETE /zones/:zone_id
  • POST /zones/:zone_id/email/routing/enable
  • POST /zones/:zone_id/email/routing/dns
  • POST /zones/:zone_id/email/routing/rules
  • DELETE /zones/:zone_id/email/routing/rules/:rule_id
  • GET /zones/:zone_id/email/routing/rules/catch_all
  • PUT /zones/:zone_id/email/routing/rules/catch_all

Required permissions:

Permission Purpose
Zone: Zone: Edit list, validate, create, and delete project-bound zones
Zone: Email Routing Rules: Edit create and delete mailbox routing rules
Zone: Zone Settings: Edit enable Email Routing

The runtime token scope must cover every zone that KaisouMail should manage. In Cloudflare's custom token builder, Zone: Zone: Edit already covers the read/list capability needed on the /zones path, so you do not need to add a separate Zone: Zone: Read row.

Catch-all addendum

  • Catch-all support does not require any new secret names. Runtime still uses CLOUDFLARE_RUNTIME_API_TOKEN, with CLOUDFLARE_API_TOKEN as the shared-token fallback.
  • Cloudflare's official API docs state:
    • GET /zones/:zone_id/email/routing/rules/catch_all accepts Email Routing Rules Read or Email Routing Rules Write
    • PUT /zones/:zone_id/email/routing/rules/catch_all requires Email Routing Rules Write
  • KaisouMail already requires Zone: Email Routing Rules: Edit, so the minimum runtime permission set does not grow when catch-all management is enabled.

Deploy token minimum permissions

The deploy flow performs:

  • wrangler deploy
  • wrangler pages deploy
  • remote D1 migrations

Required permissions:

Permission Purpose
Account: D1: Edit remote D1 migrations
Account: Workers Scripts: Edit Worker deploy
Account: Workers R2 Storage: Edit validate and bind the R2 bucket
Account: Cloudflare Pages: Edit Pages deploy
Zone: Workers Routes: Edit Worker custom-domain routes

Shared token union

If you use the shared quickstart token, it must include all of the following:

  • Zone: Zone: Edit
  • Zone: Email Routing Rules: Edit
  • Zone: Zone Settings: Edit
  • Account: D1: Edit
  • Account: Workers Scripts: Edit
  • Account: Workers R2 Storage: Edit
  • Account: Cloudflare Pages: Edit
  • Zone: Workers Routes: Edit

Common errors

Authentication error

Check these first:

  1. The token includes Zone: Zone Settings: Edit.
  2. The token scope covers the target zone.

The zone is visible but enablement still fails

This usually means the token can read the zone but cannot write the required Email Routing settings for that zone.

Related reading

References

ON THIS PAGE