Context
Migrating an app off Vercel AI Gateway to Cloudflare AI Gateway with BYOK (2026-09), I hit two documentation gaps that cost real debugging time. Filing both together since they're the same underlying trap.
Issue 1: BYOK docs don't state what happens if a client still sends an Authorization header
Page: ai-gateway/configuration/bring-your-own-keys/
The docs say: "Remove provider authorization headers from your requests. Note that you still need to pass cf-aig-authorization."
This reads as a recommendation ("you no longer need to send it"), not a hard requirement. In practice, sending any Authorization header — including an obviously-fake placeholder — causes Cloudflare to forward it to the upstream provider verbatim instead of substituting the stored BYOK key. The provider then rejects the fake value with its own error (e.g. DeepSeek: "Your api key: x is invalid"), which looks exactly like "BYOK isn't configured" rather than "you sent a header you shouldn't have."
This matters in practice because some AI SDK provider factories (e.g. @ai-sdk/openai's createOpenAI) require a non-empty apiKey string to construct at all, so a caller may reasonably pass a placeholder value assuming Cloudflare will substitute over it — which it does not.
Suggested fix: state explicitly that Cloudflare only substitutes the BYOK key when the Authorization header is absent, not merely when its value is a placeholder — and that sending a placeholder produces a provider-side auth error, not a Cloudflare-side one. A minimal repro/counter-example (curl with a fake Authorization: Bearer x vs. no header at all, side by side, showing the different failure/success) would make this unambiguous.
Issue 2: DeepSeek provider page's example doesn't show the BYOK variant
Page: ai-gateway/usage/providers/deepseek/
The only example shown is the direct-passthrough curl (Authorization: Bearer DEEPSEEK_TOKEN). The general BYOK page and some other provider pages show the header-omitted BYOK form; this page does not.
The inconsistency reads as "DeepSeek isn't supported for BYOK," which is false — it works identically to other providers once the Authorization header is dropped (confirmed working via the per-provider Universal Endpoint).
Suggested fix: add the BYOK curl variant to this page, matching the general BYOK page's example. Worth auditing other single-provider pages for the same gap.
Happy to open a PR against the docs repo instead if that's preferred — the fix is a couple of sentences + one code sample per page.
Context
Migrating an app off Vercel AI Gateway to Cloudflare AI Gateway with BYOK (2026-09), I hit two documentation gaps that cost real debugging time. Filing both together since they're the same underlying trap.
Issue 1: BYOK docs don't state what happens if a client still sends an Authorization header
Page:
ai-gateway/configuration/bring-your-own-keys/The docs say: "Remove provider authorization headers from your requests. Note that you still need to pass
cf-aig-authorization."This reads as a recommendation ("you no longer need to send it"), not a hard requirement. In practice, sending any
Authorizationheader — including an obviously-fake placeholder — causes Cloudflare to forward it to the upstream provider verbatim instead of substituting the stored BYOK key. The provider then rejects the fake value with its own error (e.g. DeepSeek:"Your api key: x is invalid"), which looks exactly like "BYOK isn't configured" rather than "you sent a header you shouldn't have."This matters in practice because some AI SDK provider factories (e.g.
@ai-sdk/openai'screateOpenAI) require a non-emptyapiKeystring to construct at all, so a caller may reasonably pass a placeholder value assuming Cloudflare will substitute over it — which it does not.Suggested fix: state explicitly that Cloudflare only substitutes the BYOK key when the Authorization header is absent, not merely when its value is a placeholder — and that sending a placeholder produces a provider-side auth error, not a Cloudflare-side one. A minimal repro/counter-example (
curlwith a fakeAuthorization: Bearer xvs. no header at all, side by side, showing the different failure/success) would make this unambiguous.Issue 2: DeepSeek provider page's example doesn't show the BYOK variant
Page:
ai-gateway/usage/providers/deepseek/The only example shown is the direct-passthrough curl (
Authorization: Bearer DEEPSEEK_TOKEN). The general BYOK page and some other provider pages show the header-omitted BYOK form; this page does not.The inconsistency reads as "DeepSeek isn't supported for BYOK," which is false — it works identically to other providers once the Authorization header is dropped (confirmed working via the per-provider Universal Endpoint).
Suggested fix: add the BYOK curl variant to this page, matching the general BYOK page's example. Worth auditing other single-provider pages for the same gap.
Happy to open a PR against the docs repo instead if that's preferred — the fix is a couple of sentences + one code sample per page.