Researched guidance: How can a Workers deployment detect an API token belonging to the wrong account?

Summary

Treat token validity, target-account reachability, and Workers permission as separate checks. Verify the token is active, call an account-scoped endpoint for the configured account and compare the returned account id when available, then perform a least-privilege Workers read/deploy preflight. Pin the same account id in Wrangler configuration or CLOUDFLARE_ACCOUNT_ID so a multi-account credential cannot silently select another account.

Candidate action

Before deployment, keep the intended 32-character account ID in configuration and run a preflight using the same authentication material as the deployment. First call GET /user/tokens/verify for a user-owned token (or GET /accounts/{account_id}/tokens/verify for an account-owned token) and require success with result.status=active; this establishes token usability, not target-account authorization (S1, S5). Next call a read-only, account-scoped endpoint that the deployment token is entitled to use—prefer GET /accounts/{account_id}/workers/scripts for a Workers deployment and require success (S7). If the token also has Account Settings Read, GET /accounts/{account_id} can be used and its result.id compared exactly with the configured account ID (S6). Treat an account-route failure, code 7003, or a returned id mismatch as a wrong-account or wrong-identifier signal; separate missing permission, expired token, and invalid object cases before retrying deployment. Keep the account ID pinned in Wrangler configuration or CLOUDFLARE_ACCOUNT_ID; Wrangler gives that explicit account selection precedence and does not fall back to another account (S3). Use a token policy limited to the deployment account where possible and the minimum Worker/resource role required (S2, S4).

Applicability

• Cloudflare Workers deployments using Wrangler, CI/CD, or direct Cloudflare API calls with CLOUDFLARE_API_TOKEN.
• User-owned or account-owned tokens can be scoped by policy to one account or broader resources; successful reachability of the intended account is the check that matters for deployment.
• The preflight should use the same token, configured account ID, and relevant Worker name/environment as the deployment.

Key findings

• Token verification returns an identifier, status, expiration, and not-before time; require active status but do not treat it as account authorization. (S1)
• Wrangler selects the account from account_id in configuration or CLOUDFLARE_ACCOUNT_ID before the profile-selected account and does not fall back to another account. (S3)
• Workers permissions are scoped at product or individual-resource level; an automated deployment normally needs Workers Editor, while new Worker creation needs product-level Admin and route changes need additional zone permission. (S2)
• Cloudflare documents code 7003 with an account_id for a different account as an incorrect-account configuration symptom. (S4)
• The account-details and Worker-script list endpoints are account-scoped API calls; the Worker-script list explicitly supports API-token authentication and can serve as a least-privilege reachability preflight, while account details can provide an id for comparison when its permission is available. (S6, S7)
• API token policies can restrict resources to one account or all accounts; use a single-account resource restriction when isolating a deployment credential. (S4)

Known limitations

• The user-token verification endpoint reports token id, status, and time bounds; it does not by itself prove access to the deployment account or the required Workers resource (S1).
• A successful account-scoped read proves the token can address that account, but does not prove every later deployment operation is permitted; Workers roles and zone route permissions remain operation-specific (S2, S6, S7).
• A 7003 response can also indicate an invalid account/object identifier or an API route/configuration problem; it is a diagnostic signal, not proof that the secret itself belongs to another account (S4).
• This is researched guidance only; no live Cloudflare request or independent reproduction was performed.

Obsolete approaches

• Do not use token verification alone as the wrong-account test.
• Do not infer account ownership from the token's opaque identifier, token name, or an account ID merely being present in configuration.

Negative results

• Cloudflare's token verification documentation does not describe a single endpoint that returns the complete set of accounts and Worker resources reachable by a user-owned token; account reachability must be checked against the intended account and operation.
• A generic token status of active does not distinguish a valid token for another account from a valid token that lacks the requested Workers permission.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• Documentation supports the preflight design and account-id comparison, but does not close a live deployment execution gap.

What remains unknown

• The exact HTTP status and error-code combination for every wrong-account, missing-permission, expired-token, and malformed-account-id case is not established by the cited documentation.
• Cloudflare may vary behavior between user-owned tokens, account-owned tokens, OAuth credentials, and Wrangler releases; validate the exact credential mode in the deployment environment.
• A successful account-details or script-list read does not guarantee that a later deployment involving routes, custom domains, bindings, or creation of a new Worker will be authorized.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 Verify Token | Cloudflare API · official_documentation · accessed 2026-09-21
• S2 Roles and permissions · Cloudflare Workers docs · official_documentation · accessed 2026-09-21
• S3 Authentication profiles · Workers - Cloudflare Docs · official_documentation · accessed 2026-09-21
• S4 Troubleshooting builds · Cloudflare Workers docs · official_documentation · accessed 2026-09-21
• S5 Verify Token | Cloudflare API - Account Owned Tokens · official_documentation · accessed 2026-09-21
• S6 Account Details | Cloudflare API · official_documentation · accessed 2026-09-21
• S7 List Worker Scripts | Cloudflare API · official_documentation · accessed 2026-09-21