← All posts

Cloudflare API Token for 2server: 5 Essential Zone Permissions

Deploying a public website through Cloudflare often halts on 401/403 even when token verification returns "active". Account permissions do not inherit Zone permissions: a public web deployment requires exactly 5 Zone permissions.

The problem: token is "active", but deploy returns 403

Anyone who has deployed a site to a VM with DNS on Cloudflare has likely hit one of two extremes:

  • Extreme one: Deploy fails with a mysterious 401/403. You create an API token, run verify, see status: "active", breathe a sigh of relief — and then the DNS record update or SSL certificate request gets rejected.
  • Extreme two: In frustration, you reach for your Global API Key — a credential with complete admin power across your entire Cloudflare account. The deployment passes, but a master secret is now sitting in configuration. If that secret leaks, your entire account is compromised, not just that single zone.

Both problems stem from the same misunderstanding of Cloudflare permissions. The Cloudflare token guide in 2server outlines the principle of least privilege: exactly 5 Zone permissions for a public website, and tokens never committed to git.


Trap one: Account permissions do not grant Zone permissions

When you create an API token in the Cloudflare dashboard, permissions are split by scope: Account and Zone. This is where most setups break:

Selecting a permission under Account does NOT automatically grant the equivalent permission under Zone.

The two layers are independent. A token with only Account permissions is completely "valid" — it authenticates against identity endpoints without issue — but cannot write to any zone. That explains many "token verified active but deploy returns 403" reports.

When configuring permissions for 2server, check two settings:

  1. Permission group — Account or Zone.
  2. Zone Resources scope — "All zones" or "Specific zone" (locking down to the target deployment zone is recommended).

Five essential Zone permissions for a public website

For a standard public web deployment — pointing DNS records, configuring SSL, managing cache rules, and issuing origin certificates — 2server documentation lists exactly 5 permissions in the Zone group:

# Permission Purpose
1 Zone — Zone — Read Read zone metadata; required to resolve the zone ID for subsequent calls
2 Zone — DNS — Edit Create and update DNS records pointing to your VM
3 Zone — Zone Settings — Edit Configure zone-level settings (such as Strict SSL mode)
4 Zone — Cache Rules — Edit Manage cache rules and purge cache after deployments
5 Zone — SSL and Certificates — Edit Issue Origin CA certificates for Cloudflare-to-origin encryption

Each permission maps to a concrete step in the deployment workflow. If a permission is missing, that exact step fails with 403 — which pinpoints what needs to be added.


Additional scopes: Email Routing, Workers, D1

The principle of least privilege applies horizontally as well. If your application relies on Email Routing or Workers/D1, these features have dedicated permission groups. Add only those permissions scoped to the required resource, rather than elevating global permissions.

Permissions map directly to features: static web requires the 5 Zone permissions above; Email Routing adds email permissions; Workers/D1 adds worker permissions. Unused features require zero permissions.


Trap two: "Verify active" does not mean "write access granted"

Cloudflare provides a verification endpoint: GET /user/tokens/verify, returning {"status": "active"}. It is tempting to treat this response as confirmation that permissions are sufficient. It is not.

Verification only validates identity: the token exists, has not been revoked, and belongs to the specified account. It says nothing about whether the token can edit DNS or issue certificates on a specific zone. A token with zero Zone permissions still verifies as "active".

When debugging permission errors:

  1. Run verification to rule out invalid tokens or mismatched accounts.
  2. If deploy still returns 403, check the token's permission groups (Account vs Zone) and scope in the dashboard.
  3. Add the specific missing permission — do not regenerate a broad token.

Avoid patching permission errors with Global API Keys

When facing deployment blockers, the reflex to temporarily assign broad admin permissions is common — and risky. Global API Keys or broad admin tokens tend to:

  • Remain in configuration files permanently ("temporary" fixes stick around).
  • Turn a leaked configuration file into full compromise of your Cloudflare account.

The proper fix is smaller: identify which deployment step triggers 403, and grant only that permission on the existing token. It takes one click in the dashboard, while keeping the token restricted to a single zone.


Storing tokens: no git, no manifests — 2srv server env

Where credentials live matters as much as their scope. 2server documentation is explicit: never store tokens in manifests, and never commit them to git. Store tokens in a private local .env file, then push them to the server:

bash
2srv server env

The complete workflow fits into four steps:

  1. Create an API token in the dashboard with the 5 Zone permissions (scoped to the specific zone).
  2. Save the token in a private local .env file — ensure this file is ignored in git.
  3. Push environment variables to your VM via 2srv server env.
  4. Deploy. If a 403 occurs, identify the failed operation and grant only that permission.

Credentials stay in server environment variables — out of repositories and public configuration files.


Pre-deployment checklist

  • Token is a scoped API Token, not a Global API Key.
  • All 5 permissions exist in the Zone group: Zone Read, DNS Edit, Zone Settings Edit, Cache Rules Edit, SSL & Certificates Edit.
  • Scope is locked to the specific deployment zone.
  • Separate permissions for Email Routing / Workers / D1 are added only when used.
  • "Verify active" is treated as identity verification, not permission validation.
  • Token lives in private .env, loaded via 2srv server env, never committed to git.

Next steps

If your Cloudflare token is stored in a manifest, or if you are using a Global API Key for quick setups, restrict it to a 5-permission Zone token and load it with 2srv server env. Full reference: 2found.dev/docs/2server/cloudflare-tokens.