[AI Gateway] Add setting to require provider credentials (#33229)

* AIG-1532: Document gateway-level BYOK requirement

* AIG-1532: Clarify BYOK-only billing behavior

* AIG-1532: Add BYOK-only changelog

* [AI Gateway] Address review feedback

* [AI Gateway] Clarify BYOK documentation

* [AI Gateway] Refine BYOK headings

Author: superhighfives

src/content/changelog/ai-gateway/2026-09-14-require-provider-credentials.mdx

@@ -0,0 +1,21 @@
+---
+title: Prevent Unified Billing fallback for BYOK third-party providers
+description: Prevent third-party provider requests from falling back to Unified Billing when provider credentials are unavailable.
+date: 2026-09-14
+---
+
+AI Gateway can now require credentials for third-party provider requests. Credentials must accompany the request or be stored on the gateway. This setting prevents fallback to Unified Billing with Cloudflare-managed credentials.
+
+Turn on **Require provider credentials** in your gateway settings. To use the API, set `byok_only` to `true` in the request body of a [`PUT` request to update the gateway](/api/resources/ai_gateway/methods/update/):
+
+```json
+{
+	"byok_only": true
+}
+```
+
+To require provider credentials for one third-party request, set the `cf-aig-no-wholesale` header to `true`. This header cannot relax the gateway setting.
+
+Requests without applicable credentials then return an HTTP `400` response. Workers AI requests remain allowed, and the setting does not change their configured billing mode.
+
+For configuration details and request-level controls, refer to [Prevent Unified Billing fallback for BYOK third-party providers](/ai-gateway/features/unified-billing/#prevent-unified-billing-fallback-for-byok-third-party-providers).

src/content/docs/ai-gateway/configuration/manage-gateway.mdx

@@ -24,13 +24,14 @@ The request that triggers auto-creation must be authenticated. When using the [R
 
 The auto-created default gateway uses the following settings:
 
-| Setting            | Default value    |
-| ------------------ | ---------------- |
-| Authentication     | On               |
-| Log collection     | On               |
-| Caching            | Off (TTL of 0)   |
-| Rate limiting      | Off              |
-| Workers AI billing | Standard billing |
+| Setting                      | Default value    |
+| ---------------------------- | ---------------- |
+| Authentication               | On               |
+| Log collection               | On               |
+| Caching                      | Off (TTL of 0)   |
+| Rate limiting                | Off              |
+| Require provider credentials | Off              |
+| Workers AI billing           | Standard billing |
 
 After creation, you can edit the default gateway settings like any other gateway. If you delete the default gateway, sending a new authenticated request to the `default` gateway ID auto-creates it again.
 
@@ -66,6 +67,10 @@ To use prepaid AI Gateway credits for Workers AI requests:
 
 Workers AI requests routed through this gateway will deduct from your AI Gateway credit balance in real time.
 
+### Prevent Unified Billing fallback for BYOK third-party providers
+
+To prevent Unified Billing fallback for third-party provider requests, turn on **Require provider credentials**. Refer to [Prevent Unified Billing fallback for BYOK third-party providers](/ai-gateway/features/unified-billing/#prevent-unified-billing-fallback-for-byok-third-party-providers) for dashboard and API instructions.
+
 ## Retry requests
 
 You can configure your gateway to automatically retry failed requests to upstream providers. This is useful when you do not control the client and cannot implement client-side retries or backoff logic.

src/content/docs/ai-gateway/features/unified-billing.mdx

@@ -11,7 +11,7 @@ products:
   - ai-gateway
 ---
 
-import { DashButton, Render, TabItem, Tabs } from "~/components";
+import { DashButton, Render, Steps, TabItem, Tabs } from "~/components";
 
 Unified Billing allows users to call Workers AI and connect to various AI providers (such as OpenAI, Anthropic, and Google AI Studio) and receive a single Cloudflare bill. To use Unified Billing, you must purchase and load credits into your Cloudflare account in the Cloudflare dashboard, which you can then spend with AI Gateway.
 
@@ -70,6 +70,32 @@ On requests routed through Unified Billing endpoints (for example, `env.AI.run()
 The `cf-aig-byok-alias` header selects a non-default alias only on [direct provider-passthrough](/ai-gateway/usage/providers/) requests.
 :::
 
+## Prevent Unified Billing fallback for BYOK third-party providers
+
+Turn on **Require provider credentials** to prevent Unified Billing fallback for third-party providers. Third-party provider requests must use credentials supplied with the request or stored on the gateway. Requests without applicable credentials return an HTTP `400` response instead of using Cloudflare-managed credentials.
+
+<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
+
+<Steps>
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and go to **AI** > **AI Gateway**.
+
+   <DashButton url="/?to=/:account/ai/ai-gateway" />
+
+2. Select your gateway.
+3. Go to **Settings** and turn on **Require provider credentials**.
+4. Confirm the change.
+</Steps>
+
+</TabItem> <TabItem label="API">
+
+Send a [`PUT` request](/api/resources/ai_gateway/methods/update/) to update the gateway. Include `byok_only: true` in the request body.
+
+</TabItem> </Tabs>
+
+To require provider credentials for one third-party provider request, set the `cf-aig-no-wholesale` header to `true`. This header can prevent Unified Billing fallback but cannot relax the gateway setting. If **Require provider credentials** is on, setting the header to `false` has no effect.
+
+Workers AI requests do not use provider credentials. This setting does not block these requests or change the gateway's configured Workers AI billing mode.
+
 ## Use Unified Billing
 
 Unified Billing works in two ways: through the AI binding or through the HTTP API. Both deduct credits from your account automatically without requiring provider API keys.

src/content/docs/ai-gateway/glossary.mdx

@@ -24,3 +24,5 @@ Settings in AI Gateway can be configured at two levels: **Request** and **Gatewa
    Act as the default if no headers are set at the request level.
 
 This hierarchy ensures consistent behavior, prioritizing the most specific configurations. Use request-level headers for fine-tuned control, and gateway settings for general defaults.
+
+Some restrictive settings are additive. The `cf-aig-no-wholesale` header can require provider credentials for a third-party provider request, but it cannot turn off **Require provider credentials** when that gateway setting is on.

src/content/glossary/ai-gateway.yaml

@@ -61,6 +61,10 @@ entries:
     general_definition: |-
       A response header returned when a [DLP policy](/ai-gateway/features/dlp/set-up-dlp/#dlp-response-header) matches a request or response. Contains JSON with the action taken (Flag or Block), matched policy IDs, matched profile IDs, and detection entry IDs.
 
+  - term: cf-aig-no-wholesale
+    general_definition: |-
+      Prevents [Unified Billing fallback](/ai-gateway/features/unified-billing/#prevent-unified-billing-fallback-for-byok-third-party-providers) for a third-party provider request when set to `true`. The request must use provider credentials supplied with the request or stored on the gateway.
+
   # Deprecated headers
   - term: cf-cache-ttl
     general_definition: |-