[AI Gateway] Correct required API token permission for REST API

[kai-cloudflare]

Summary

The Authentication section of the AI Gateway REST API page states that the token needs the AI Gateway permission. That permission does not grant access to these endpoints. A token holding only AI Gateway Read or AI Gateway Run returns 401 with error code 10000.

The permission the /accounts/{account_id}/ai/* endpoints actually require is Workers AI Read, whose own permission group description is "Grants access to invoke Workers AI models". This holds for third-party models as well as @cf/ models, because the check applies to the API path rather than to the routed provider.

How this was verified

Four single-permission user API tokens, each scoped to one account, against POST /accounts/{account_id}/ai/v1/chat/completions with model: openai/gpt-4.1 (a third-party model):

Token permission	GET /ai-gateway/gateways	POST /ai/v1/chat/completions
AI Gateway Read	200	401 / 10000
AI Gateway Run	403	401 / 10000
Workers AI Read	403	402 / 2021 (reached gateway)
Workers AI Edit	403	402 / 2021 (reached gateway)

The 402 responses are Unified Billing rejections raised inside AI Gateway, which confirms the request passed authentication and reached the gateway.

With a Workers AI Read token only, the following also pass authentication:

• POST /ai/run
• requests carrying cf-aig-gateway-id
• requests targeting a dynamic route (model: dynamic/{route})
• @cf/ models on the same token

Impact

This wording sends users to configure AI Gateway Run, which produces a 401 with no entry in AI Gateway logs, because the request is rejected before it reaches the gateway. The failure is indistinguishable from an invalid token, so it is expensive to diagnose from the response alone.

[cloudflare-docs-bot]

Review

✅ No issues found in commit 1e11f4b.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

_{No code review issues found.}

Conventions

_{No convention issues found.}

Style Guide Review

_{No style-guide issues found.}

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review	Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.
/rebase	Rebases the PR branch against production. On conflict, attempts to resolve automatically using AI. Stops with an explanation if confidence is not high enough.