Cloudflare AI Gateway BYOK-only: stop silent Unified Billing fallback
Quick answer
Cloudflare AI Gateway can now require customer-supplied credentials for third-party provider requests. Enable Require provider credentials in the dashboard, or set byok_only: true through the gateway API. A third-party request without an applicable request key or stored BYOK key then returns HTTP 400 instead of falling through to Cloudflare-managed credentials and Unified Billing.
The request header cf-aig-no-wholesale: true applies the same restriction to one request, but it cannot weaken a gateway-wide requirement. Workers AI requests remain allowed and keep their configured billing mode. Roll this out with credential, alias, route, and billing canaries; a successful model response alone does not prove which credential or bill paid for it.
Who this is for
This checklist is for teams using AI Gateway to route OpenAI, Anthropic, Google, or other third-party models while expecting spend to remain on their own provider accounts. It is especially useful when a missing BYOK secret could previously produce a successful response through Unified Billing instead of an obvious configuration failure.
If you intentionally use Unified Billing, do not enable the gateway-wide control blindly. First classify which routes must be BYOK-only and which are expected to use Cloudflare billing.
What changed, and why it matters now
Cloudflare announced the control on September 14, 2026. The new gateway setting changes a missing-credential path from a fallback into a visible error. That matters because availability and billing correctness are different acceptance criteria: a request can succeed while using an unintended credential source.
The documented boundary is narrow:
| Surface | New behavior | Boundary |
|---|---|---|
| Gateway |
byok_only: true requires provider credentials for third-party requests |
A request header cannot turn this requirement off |
| One request |
cf-aig-no-wholesale: true prevents Unified Billing fallback |
It can make a route stricter, not less strict |
| Missing applicable credential | Third-party request returns HTTP 400
|
Treat this as a useful policy failure, not a provider outage |
| Workers AI | Requests remain allowed | The setting does not change their configured billing mode |
Do not infer that every successful request used a stored key. Credential precedence and aliases still determine which key is applicable.
Map credential precedence before rollout
Create a route inventory with one row per provider, endpoint style, and environment. Record whether the request supplies a provider authorization header, whether AI Gateway stores a default BYOK key, whether a non-default alias is selected, and whether the route intentionally uses Unified Billing.
Cloudflare documents an important alias boundary: cf-aig-byok-alias selects a non-default alias on direct provider-passthrough requests. Unified Billing endpoints, including AI binding paths, consult only the default stored key; if it is missing, they may otherwise fall through to Unified Billing. This is the exact drift that BYOK-only can expose.
| Route shape | Credential expected | BYOK-only expectation |
|---|---|---|
| Direct provider passthrough with request key | Request-supplied provider key | Success and provider-side usage evidence |
| Direct passthrough with stored default key | Gateway BYOK default alias |
Success and matching gateway/provider logs |
| Direct passthrough with named alias | Stored named alias plus cf-aig-byok-alias
|
Success only for the selected alias |
| Unified endpoint with stored named alias only | No applicable default key | HTTP 400, not silent fallback |
| Third-party route with no provider credentials | None | HTTP 400 when either restriction is active |
| Workers AI route | Configured Workers AI billing mode | Continues under that mode |
Six-canary rollout workflow
1. Capture the current gateway and bill source
Export the gateway settings without secrets. Record gateway ID, environment, route, provider, current byok_only value, expected credential source, and the most recent matching provider or Cloudflare billing event.
2. Start with one non-production gateway
Enable Require provider credentials in the dashboard, or update the gateway with the documented API and "byok_only": true. Read the gateway back and archive the returned setting. An accepted update request is not proof that the effective configuration changed.
3. Replay three positive canaries
Send one request with an explicit provider key, one using the stored default BYOK key, and one direct passthrough request selecting a named alias. Use tiny deterministic prompts and cap tokens. Each run needs a terminal response, an AI Gateway log identifier, and provider-side usage where available.
4. Replay two negative canaries
Remove applicable provider credentials from a harmless test request. First rely on the gateway-wide setting; then test a separate gateway with only cf-aig-no-wholesale: true. Both third-party requests should return HTTP 400. Never paste real keys into the test transcript.
5. Verify the Workers AI boundary
Run one bounded Workers AI request through the same gateway. It should remain allowed. Record its configured billing mode separately; do not use this successful request as proof that third-party BYOK behavior passed.
6. Reconcile billing before promotion
Wait for the relevant usage records, then match gateway log ID, provider request, model, timestamp window, and billed account. Promote only when positive canaries use the intended provider account, negative canaries fail closed, and the Workers AI control behaves independently.
Acceptance matrix
| Canary | Expected result | Evidence |
|---|---|---|
| Request-supplied provider key | Success | Gateway log plus provider usage |
Stored default key |
Success | Gateway log plus matching stored-key route |
| Named alias on direct passthrough | Success | Selected alias recorded; no fallback |
| No credential, gateway BYOK-only | HTTP 400
|
Response status and gateway log |
| No credential, request header only | HTTP 400
|
cf-aig-no-wholesale: true in secret-safe fixture |
| Workers AI control | Success under configured mode | Separate Workers AI billing evidence |
Copyable rollout receipt
date:
gateway_id:
environment:
route_style: direct-passthrough | unified-endpoint | workers-ai
provider:
model:
byok_only_readback: true | false
request_restriction_header: true | false
credential_source: request | stored-default | stored-alias | none | workers-ai
expected_status:
observed_status:
gateway_log_id:
provider_usage_evidence:
cloudflare_billing_evidence:
result: pass | fail | blocked
rollback_owner:
The existing AI Gateway spend checklist is useful for the reconciliation step. If a gateway reports an authentication failure, keep credential recovery separate from policy relaxation; the gateway authentication recovery checklist shows that pattern.
Common mistakes
The main mistake is treating HTTP 200 as proof of BYOK. Other errors include storing only a named alias for a Unified endpoint that consults default, assuming a request header can relax the gateway setting, classifying the expected HTTP 400 as downtime, and mixing Workers AI billing evidence with third-party provider evidence.
Building something? Turn your product page into a show people want to watch with PromoFast—hosted, embeddable, and ready to export.
FAQ
Does BYOK-only disable Unified Billing everywhere?
No. It prevents fallback for third-party provider requests on the restricted gateway or request. Workers AI remains allowed and keeps its configured billing mode.
Can cf-aig-no-wholesale: false override a BYOK-only gateway?
No. Cloudflare states that the request-level control can make a request stricter but cannot relax the gateway-wide requirement.
Why does a stored named alias still fail on a Unified endpoint?
Cloudflare documents that Unified Billing endpoints consult only the stored default alias. Use a direct provider-passthrough route when selecting a non-default alias, or configure the intended default key.
Is an HTTP 400 a failed rollout?
For a negative missing-credential canary, it is the expected fail-closed result. It is a rollout failure only when a route that should have an applicable credential also returns 400.
Sources
- Cloudflare changelog — Prevent Unified Billing fallback for BYOK third-party providers
- Cloudflare AI Gateway — Unified Billing
- Cloudflare AI Gateway — BYOK stored keys
- Cloudflare AI Gateway — header glossary and configuration hierarchy
Originally published on IndieSeek.
Top comments (0)