Proposed changes
Subject Matter
Document that AI Gateway API token permissions are account-scoped only (no per-gateway scope), unlike R2's per-bucket scoping
Content Location
A call-out on the API token permissions reference
(https://developers.cloudflare.com/fundamentals/api/reference/permissions/) where
AI Gateway Read/Edit/Run are listed, and a matching note on the AI Gateway
Authenticated Gateway page. New call-outs within existing pages — not a new page.
Additional information
The AI Gateway Run (and Read/Edit) permission can only be granted at account scope —
the IAM resources catalog exposes no per-gateway resource type, so a token policy must
use com.cloudflare.api.account.<id>: "*". This means any token with AI Gateway Run
authorizes calls to every AI Gateway in the account; it cannot be narrowed to a single
gateway.
This is not stated in the permissions docs, and it contrasts with R2, which DOES support
sub-account scoping (com.cloudflare.edge.r2.bucket.<...>) to limit a token to one bucket.
Readers reasonably assume AI Gateway has a comparable per-gateway scope; it doesn't.
Why it matters: when multiple instances/tenants share a Cloudflare account and each holds
its own AI Gateway token, a leaked or compromised token is not contained to its own
gateway — it can reach (and spend BYOK budget through) any gateway in the account. Calling
out the account-only scope lets architects design around it (e.g. separate accounts, or a
Worker-side AI Gateway binding) instead of discovering it after the fact.
Suggested call-out wording:
Note: AI Gateway permissions (AI Gateway Read/Edit/Run) are account-scoped only.
Unlike R2 (which supports per-bucket token scoping), there is currently no resource type
to scope an API token to a single AI Gateway. A token with AI Gateway Run can call any
gateway in the account; it cannot be restricted to one.
A feature request to add per-AI-Gateway token scoping is tracked separately on the
Cloudflare Community:
https://community.cloudflare.com/t/scope-api-tokens-to-a-specific-ai-gateway-matching-the-per-bucket-scoping-r2-alrea/930329
This issue only asks for the documentation to state the current account-only constraint.
Proposed changes
Subject Matter
Document that AI Gateway API token permissions are account-scoped only (no per-gateway scope), unlike R2's per-bucket scoping
Content Location
A call-out on the API token permissions reference
(https://developers.cloudflare.com/fundamentals/api/reference/permissions/) where
AI Gateway Read/Edit/Run are listed, and a matching note on the AI Gateway
Authenticated Gateway page. New call-outs within existing pages — not a new page.
Additional information
The
AI Gateway Run(and Read/Edit) permission can only be granted at account scope —the IAM
resourcescatalog exposes no per-gateway resource type, so a token policy mustuse
com.cloudflare.api.account.<id>: "*". This means any token with AI Gateway Runauthorizes calls to every AI Gateway in the account; it cannot be narrowed to a single
gateway.
This is not stated in the permissions docs, and it contrasts with R2, which DOES support
sub-account scoping (
com.cloudflare.edge.r2.bucket.<...>) to limit a token to one bucket.Readers reasonably assume AI Gateway has a comparable per-gateway scope; it doesn't.
Why it matters: when multiple instances/tenants share a Cloudflare account and each holds
its own AI Gateway token, a leaked or compromised token is not contained to its own
gateway — it can reach (and spend BYOK budget through) any gateway in the account. Calling
out the account-only scope lets architects design around it (e.g. separate accounts, or a
Worker-side AI Gateway binding) instead of discovering it after the fact.
Suggested call-out wording:
A feature request to add per-AI-Gateway token scoping is tracked separately on the
Cloudflare Community:
https://community.cloudflare.com/t/scope-api-tokens-to-a-specific-ai-gateway-matching-the-per-bucket-scoping-r2-alrea/930329
This issue only asks for the documentation to state the current account-only constraint.