zuplo 7.7.8 → 7.7.10

package/docs/ai-gateway/integrations/claude-code.mdx

@@ -10,6 +10,17 @@ You can configure [Claude Code](https://www.claude.com/product/claude-code) to
 send its model requests through the Zuplo AI Gateway, so the gateway
 authenticates, meters, and routes every Claude Code session.
 
+The gateway can authenticate to Anthropic in two ways. Pick one before you
+configure Claude Code:
+
+| Approach                                                  | The gateway sends Anthropic                                           | Claude Code sends the gateway                                             |
+| --------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| [Configured provider key](#use-a-configured-provider-key) | The Anthropic API key saved on your provider                          | The app's API key as `ANTHROPIC_AUTH_TOKEN`                               |
+| [Your Claude subscription](#use-your-claude-subscription) | The credential from your `claude.ai` login, such as a Claude Max plan | The app's API key in a `zp-gateway-api-key` header, plus your login as-is |
+
+Both approaches share the same provider, team, and app setup, and the same model
+configuration.
+
 ## Claude Code Setup
 
 <Stepper>
@@ -19,12 +30,18 @@ authenticates, meters, and routes every Claude Code session.
 
 2. [Set up a new team](../managing-teams.mdx)
 
-3. Create a [new app](../managing-apps.mdx) to use with Claude Code and assign
+3. If you plan to use your Claude subscription, configure the team's
+   [API Key Authentication policy](#configure-the-api-key-authentication-policy)
+   for passthrough before you create the app
+
+4. Create a [new app](../managing-apps.mdx) to use with Claude Code and assign
    it to the team you created
 
-4. Copy the **API URL** and **API Key** shown at the top of the app page
+5. Copy the **API URL** and **API Key** shown at the top of the app page
 
-5. Add the API key, gateway URL, and model mappings to `.claude/settings.json`
+6. Add the gateway URL, the app's API key, and model mappings to
+   `.claude/settings.json`, following the section below for the approach you
+   chose
 
 </Stepper>
 
@@ -45,7 +62,7 @@ The gateway routes every request using `providerName/model`. The provider prefix
 picks which of your providers handles the request — a gateway can contain
 several providers that serve Anthropic models.
 
-### Using settings.json
+### Where Claude Code reads its settings
 
 You can configure Claude Code either globally or per project by editing the
 settings file:
@@ -53,6 +70,23 @@ settings file:
 - **Global:** `~/.claude/settings.json`
 - **Project-specific:** `.claude/settings.json` in your project directory
 
+Each approach below shows the `env` block to add to that file. Restart Claude
+Code after saving it, and all your Claude Code LLM requests route through the AI
+Gateway.
+
+:::note
+
+Claude Code appends `/v1/messages` to the base URL itself, so
+`ANTHROPIC_BASE_URL` is the app's URL _without_ the `/v1` suffix.
+
+:::
+
+## Use a configured provider key
+
+With this approach the gateway calls Anthropic with the API key you saved on the
+[provider](../managing-providers.mdx). Claude Code presents only the app's API
+key, and Anthropic bills the account that owns the provider key.
+
 Add the following environment configuration to the settings file:
 
 ```json
@@ -70,17 +104,138 @@ Add the following environment configuration to the settings file:
 }
 ```
 
-:::note
+`ANTHROPIC_AUTH_TOKEN` replaces whatever login Claude Code would otherwise use,
+so this approach doesn't consume your Claude subscription.
 
-Claude Code appends `/v1/messages` to the base URL itself, so
-`ANTHROPIC_BASE_URL` is the app's URL _without_ the `/v1` suffix.
+## Use your Claude subscription
 
-:::
+With this approach Claude Code stays signed in to `claude.ai` — for example with
+a Claude Max plan — and the gateway forwards that login credential to Anthropic
+as the request's provider credential. The app's API key travels in a separate
+`zp-gateway-api-key` header, so the gateway still authenticates the app, applies
+its policy chain, and meters its usage.
+
+Two pieces of configuration make this work: the app's **API Key Authentication**
+policy accepts the app key from the `zp-gateway-api-key` header and passes the
+`Authorization` header through, and Claude Code sends both headers.
+
+### Configure the API Key Authentication policy
+
+The [API Key Authentication](../../policies/ai-gateway-auth-v2-inbound.mdx)
+policy needs three options for passthrough:
+
+| Option                  | Value                | Effect                                                   |
+| ----------------------- | -------------------- | -------------------------------------------------------- |
+| `credentialPassthrough` | On                   | Forward the caller's `Authorization` header to Anthropic |
+| `authHeader`            | `zp-gateway-api-key` | Read the app's API key from this header instead          |
+| `authScheme`            | Empty value          | The header holds the bare key, with no `Bearer` prefix   |
+
+You can set these options on the team's
+[policy template](../policy-templates.mdx), so every app created in the team
+starts with passthrough enabled, or on a single app's **Policies** tab. The
+steps below use the team template; the app's policy editor works the same way.
+
+<Stepper>
+
+1. Open the team in the Zuplo Portal and select its **Policy Template** tab.
+
+2. Click the edit (pencil) icon on the **API Key Authentication** entry.
+
+3. Turn on **credentialPassthrough**.
+
+4. Set **authHeader** to `zp-gateway-api-key`.
+
+5. Leave **authScheme** blank and click **Use an empty value for authScheme**.
+   The field then reports "Empty value set. The default (Bearer) is not
+   applied." Clearing the field alone isn't enough: a blank field omits the
+   option, so the `Bearer` default still applies and every request fails with
+   `401 Invalid Authorization Scheme`.
+
+6. Click **Apply**, then **Save changes**.
+
+</Stepper>
+
+The **JSON** editor mode shows the equivalent options:
+
+```json
+{
+  "credentialPassthrough": true,
+  "authHeader": "zp-gateway-api-key",
+  "authScheme": ""
+}
+```
+
+### The provider still needs an API key
+
+The Portal requires an API key to save an Anthropic provider, and passthrough
+requests never send it: the request to Anthropic carries the caller's credential
+instead. Anything else that uses this provider's configured credential still
+needs a real key. That includes apps on this gateway that don't use passthrough
+and any
+[Fallback Model](../../policies/ai-gateway-fallback-model-v2-inbound.mdx)
+target, because fallback requests use the provider's configured credential
+rather than the caller's. If nothing on the gateway uses the configured
+credential, a placeholder value works.
+
+The app's playground in the Portal sends the app key as a bearer token in
+`Authorization`, so it can't call an app that uses passthrough. Test the app
+from Claude Code instead, as described below.
+
+### Configure Claude Code
+
+Add the following environment configuration to the settings file. Don't set
+`ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` here or in your shell: either one
+replaces your `claude.ai` login, and the gateway would then forward that value
+to Anthropic as the credential.
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e",
+    "ANTHROPIC_CUSTOM_HEADERS": "zp-gateway-api-key: <your-ai-gateway-app-api-key>",
+    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-5",
+    "ANTHROPIC_SMALL_FAST_MODEL": "anthropic/claude-haiku-4-5",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4-5",
+    "ANTHROPIC_DEFAULT_FABLE_MODEL": "anthropic/claude-fable-5"
+  }
+}
+```
+
+`ANTHROPIC_CUSTOM_HEADERS` adds the `zp-gateway-api-key` header to every request
+Claude Code makes, while Claude Code keeps sending its own `Authorization`
+header from your login. The gateway consumes those incoming headers, uses the
+login credential to authenticate the Anthropic request, and never sends your app
+key to Anthropic.
+
+### Verify the subscription setup
+
+Restart Claude Code, then confirm which credential it's using and send one
+request through the gateway:
+
+```bash
+claude auth status --text
+claude -p "Reply with the single word OK"
+```
+
+The first command should report that you're signed in with your `claude.ai`
+account rather than an API key or auth token. The second returns a short reply,
+and the request appears in the app's usage in the Zuplo Portal. In an
+interactive session, `/status` shows the same login information.
+
+If the request fails:
 
-Restart Claude and it will switch to using your new AI Gateway configuration and
-all your Claude Code LLM requests will route through the AI Gateway.
+- `401` with `Invalid Authorization Scheme` — `authScheme` still has its
+  `Bearer` default. Set it to an explicit empty value in the policy.
+- `401` with `Header configured by options.authHeader is missing` — Claude Code
+  didn't send `zp-gateway-api-key`. Check `ANTHROPIC_CUSTOM_HEADERS`.
+- `401` with `credentialPassthrough requires a non-empty Authorization header` —
+  Claude Code isn't signed in. Run `claude` and use `/login`.
+- An authentication error from Anthropic — Anthropic rejected the forwarded
+  login credential. Sign in to Claude Code again.
 
-### Configure every Claude Code model variable
+## Configure every Claude Code model variable
 
 The model ids in these examples reflect what was current when this page was
 written, and ids differ across providers — a Bedrock provider serves different

package/docs/ai-gateway/managing-providers.mdx

@@ -53,9 +53,12 @@ To add a new AI provider to your Zuplo AI Gateway, follow these steps:
    [Zuplo Demo provider](./providers.mdx#zuplo-demo) asks for no API key—your
    gateway authenticates to the demo service itself,
    [Bedrock Mantle](./bedrock-mantle.mdx) additionally asks for an **AWS
-   Region** and accepts only long-term Bedrock API keys, and
+   Region** and accepts only long-term Bedrock API keys,
    [Vertex AI](./vertex-ai.mdx) asks for a **Location** and a **Google Cloud
-   Project ID** and takes a service account JSON key file instead of an API key.
+   Project ID** and takes a service account JSON key file instead of an API key,
+   and [Azure AI](./azure-ai.mdx) asks for an **Azure Resource Name** and a host
+   family, plus a mapping for any deployment named differently from the model it
+   serves.
 
 1. Select the model or models you want to use with this provider. The available
    models will depend on the selected provider. This can be changed later.
@@ -85,10 +88,11 @@ To modify an existing provider, open
 and click the **Edit** button next to the provider you want to modify.
 
 You can modify the API key and selected models for the provider—and, for
-[Bedrock Mantle](./bedrock-mantle.mdx), the AWS Region, or for
-[Vertex AI](./vertex-ai.mdx), the Location and Google Cloud Project ID. The
-**Provider Name** isn't editable: it's the routing address in every
-`providerName/model` reference, so renaming it would orphan each stored
+[Bedrock Mantle](./bedrock-mantle.mdx), the AWS Region, for
+[Vertex AI](./vertex-ai.mdx), the Location and Google Cloud Project ID, or for
+[Azure AI](./azure-ai.mdx), the Azure Resource Name, host family, and deployment
+mappings. The **Provider Name** isn't editable: it's the routing address in
+every `providerName/model` reference, so renaming it would orphan each stored
 reference to this provider. After making your changes, click **Save** to apply
 them.
 

package/docs/ai-gateway/overview.mdx

@@ -75,8 +75,9 @@ usage limits still apply.
 ### Multi-Provider Support
 
 Configure multiple LLM providers within a single AI Gateway project. Supported
-providers include OpenAI, Anthropic, Google, Mistral, xAI, Amazon Bedrock
-(through [Bedrock Mantle](./bedrock-mantle.mdx)), Google Cloud
+providers include OpenAI, Anthropic, Google, Mistral, xAI, Microsoft Azure
+(through [Azure AI](./azure-ai.mdx)), Amazon Bedrock (through
+[Bedrock Mantle](./bedrock-mantle.mdx)), Google Cloud
 ([Vertex AI](./vertex-ai.mdx)), and OpenAI-compatible custom providers. See
 [AI Providers](./providers.mdx) for the full list of providers and supported
 capabilities. Apps reference models as `providerName/model`—for example

package/docs/ai-gateway/providers.mdx

@@ -19,6 +19,8 @@ Zuplo currently supports the following AI providers:
 - Google
 - Mistral
 - xAI (Grok)
+- [Azure AI](./azure-ai.mdx)—Azure OpenAI and Microsoft Foundry resources,
+  serving Claude and every Foundry model family from your own Azure subscription
 - [Bedrock Mantle](./bedrock-mantle.mdx)—Amazon Bedrock's compatible-APIs
   endpoint, serving Claude models and models from many other vendors
 - [Vertex AI](./vertex-ai.mdx)—Google Cloud's managed model platform, serving
@@ -36,6 +38,7 @@ The following capabilities are supported across providers:
 | Google                     | ✅               | ✅         | ❌        | ❌       |
 | Mistral                    | ✅               | ✅         | ❌        | ❌       |
 | xAI                        | ✅               | ✅         | ❌        | ❌       |
+| Azure AI                   | ✅               | ✅         | ✅        | ✅       |
 | Bedrock Mantle             | ✅               | ❌         | ✅        | ✅       |
 | Vertex AI                  | ✅               | ✅         | ❌        | ✅       |
 | Zuplo Demo                 | ✅               | ❌         | ❌        | ❌       |
@@ -51,6 +54,16 @@ Messages (plus chat completions through translation), while its other models
 serve chat completions and—per model—Responses. See
 [Using Bedrock Mantle](./bedrock-mantle.mdx#supported-endpoints-by-model-family).
 
+Azure AI's capabilities split by model family, and within the OpenAI-compatible
+family they split per deployed model: a chat model serves chat completions and—
+per model and version—Responses, while an embedding model serves embeddings and
+neither of the others. Claude serves Messages (plus chat completions through
+translation) and needs a Microsoft Foundry resource, since Claude can't be
+deployed on an Azure OpenAI resource. Azure also addresses models by
+**deployment name** rather than by published model ID, so a deployment named
+differently from the model it serves needs mapping for the gateway to price it.
+See [Using Azure AI](./azure-ai.mdx#azure-serves-deployments-not-model-names).
+
 A custom provider must serve chat completions and embeddings under a `/v1` path
 segment on its API URL, and you enter that URL as an origin root—without the
 `/v1` suffix vendors usually publish. See
@@ -61,6 +74,32 @@ Apps reference a provider's models as `providerName/model`—for example
 name you give the provider configuration. See the
 [Universal API](./universal-api.mdx).
 
+## Azure AI
+
+**Azure AI** serves models from your own Azure resource. One provider
+configuration covers both kinds of resource, and which capabilities apply
+depends on the resource and the model:
+
+- An **Azure OpenAI** resource deploys OpenAI models and serves chat
+  completions, embeddings, and the Responses API.
+- A **Microsoft Foundry** resource serves those plus every Foundry model
+  family—Grok, DeepSeek, Llama, Mistral, Phi, Kimi and more—and serves **Claude
+  models** on the native Anthropic Messages API, with chat completions through
+  the gateway's translation.
+
+Two things make Azure different from every other provider:
+
+- **It addresses deployments, not published model IDs.** You name deployments
+  when you create them in Azure, and that name is what goes in the `model`
+  field. A deployment whose name differs from the model it serves needs a
+  mapping, or the gateway can't price its usage.
+- **Its endpoint host embeds your resource name.** The provider dialog asks for
+  an **Azure Resource Name** and a host family rather than a full URL, and it
+  takes a resource key—not a Microsoft Entra ID token.
+
+For prerequisites, setup steps, code examples, and troubleshooting, see
+[Using Azure AI](./azure-ai.mdx).
+
 ## Bedrock Mantle
 
 **Bedrock Mantle** is Amazon Bedrock's compatible-APIs endpoint. One regional

package/docs/ai-gateway/universal-api.mdx

@@ -63,9 +63,9 @@ list—so clients that can't set a model still work.
 
 ## Supported endpoints
 
-| Endpoint               | Notes                                                                                                                               |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `/v1/chat/completions` | Chat completions for every provider                                                                                                 |
-| `/v1/embeddings`       | Embeddings for every provider except Anthropic                                                                                      |
-| `/v1/responses`        | OpenAI Responses API: OpenAI, and [Bedrock Mantle](./bedrock-mantle.mdx) OpenAI-compatible models that serve it                     |
-| `/v1/messages`         | Anthropic Messages API: Anthropic, and the Claude models of [Bedrock Mantle](./bedrock-mantle.mdx) and [Vertex AI](./vertex-ai.mdx) |
+| Endpoint               | Notes                                                                                                                                                           |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/v1/chat/completions` | Chat completions for every provider                                                                                                                             |
+| `/v1/embeddings`       | Embeddings for the providers marked in the [capability matrix](./providers.mdx#supported-providers)                                                             |
+| `/v1/responses`        | OpenAI Responses API: OpenAI, and the OpenAI-compatible models that serve it on [Azure AI](./azure-ai.mdx) and [Bedrock Mantle](./bedrock-mantle.mdx)           |
+| `/v1/messages`         | Anthropic Messages API: Anthropic, and the Claude models of [Azure AI](./azure-ai.mdx), [Bedrock Mantle](./bedrock-mantle.mdx) and [Vertex AI](./vertex-ai.mdx) |

package/docs/ai-gateway/vertex-ai.mdx

@@ -129,7 +129,12 @@ send your traffic and your spend to someone else's Google Cloud project.
 | `/v1/chat/completions` | ✅ Forwarded                   | ❌            |
 | `/v1/embeddings`       | ✅ Translated                  | ❌            |
 | `/v1/responses`        | ❌                             | ❌            |
-| `/v1/messages`         | ❌                             | ✅ Native     |
+| `/v1/messages`         | ❌                             | ✅ Forwarded  |
+
+**Forwarded** means the gateway sends your request on in the shape you wrote it.
+**Translated** means it converts between two API shapes—for embeddings, from the
+OpenAI shape onto Vertex's own embedding APIs, which is invisible from your
+side.
 
 Streaming (`stream: true`) works on chat completions and on Messages.
 

package/docs/policies/_index.md

@@ -4,7 +4,7 @@
 | --- | --- | --- | --- |
 | set-query-params-inbound | Add or Set Query Parameters | Adds or sets query parameters on the incoming request. | api-gateway |
 | set-headers-inbound | Add or Set Request Headers | Adds or sets headers on the incoming request. | api-gateway |
-| ai-gateway-auth-v2-inbound | AI Gateway Authentication | Authenticates requests to an AI Gateway endpoint with application API keys.  Add this policy to an application's `inboundPolicyChain` to require a key for that app only, or place it on the route before the configuration executor to require a key for every application on the route. The policies that follow can read the authenticated application from `request.user` (`sub` is the application name, `data` its metadata), and the application's AI Gateway configuration takes effect for the request. Use `authHeader` and `authScheme` when clients send their app key somewhere other than the default `Authorization: Bearer` header.  When the matched route captures an `app_id` path parameter (platform catch-all `/:app_id/(.*)`), this policy also requires `configuration.id === request.params.app_id` and returns 403 on mismatch. | ai-gateway |
+| ai-gateway-auth-v2-inbound | AI Gateway Authentication | Authenticates requests to an AI Gateway endpoint with application API keys.  Add this policy to an application's `inboundPolicyChain` to require a key for that app only, or place it on the route before the configuration executor to require a key for every application on the route. The policies that follow can read the authenticated application from `request.user` (`sub` is the application name, `data` its metadata), and the application's AI Gateway configuration takes effect for the request. Use `authHeader` and `authScheme` when clients send their app key somewhere other than the default `Authorization: Bearer` header. Enable `credentialPassthrough`, with the application key in a separate header, to forward the caller's `Authorization` header to the primary provider as its credential.  When the matched route captures an `app_id` path parameter (platform catch-all `/:app_id/(.*)`), this policy also requires `configuration.id === request.params.app_id` and returns 403 on mismatch. | ai-gateway |
 | ai-gateway-configuration-executor-v2-inbound | AI Gateway Configuration Executor | Loads the app configuration for the request (when auth or the configuration loader has not already), runs the inbound policy chain from that configuration, and enforces limits inherited from parent teams or the gateway root.  Place this policy on AI Gateway routes after optional authentication and optional `ai-gateway-configuration-loader-v2-inbound`. When either of those already populated the app-configuration channel, this policy reuses it. Otherwise it loads the configuration with the route's `app_id` path parameter. Applications select from policies pre-declared by the gateway. Applications without a `inboundPolicyChain`, or with an empty chain, run no application-selected policies. Entry options replace the declaration's options as a complete object; omit them to inherit the declaration, including environment-backed credentials. Each occurrence receives a private deep copy of its entry options, so a policy mutating its options cannot corrupt the cached app configuration. | ai-gateway |
 | ai-gateway-configuration-loader-v2-inbound | AI Gateway Configuration Loader | Loads the AI Gateway app configuration for the request into the request-scoped channel and does nothing else.  Place this policy on AI Gateway routes before `ai-gateway-configuration-executor-v2-inbound` when you want configuration loading separated from chain execution. When `ai-gateway-auth-v2-inbound` already populated the channel, this policy reuses it. Otherwise it loads the configuration with the route's `app_id` path parameter.  If this policy is omitted, the configuration executor still loads configuration itself before running the application chain. | ai-gateway |
 | ai-gateway-fallback-model-v2-inbound | AI Gateway Fallback Model | Adds failure and quota fallbacks to an existing AI Gateway model selection.  Place this policy after AI Gateway Model Filtering. It never creates a model selection, so a misplaced policy cannot bypass filtering. | ai-gateway |

package/docs/policies/ai-gateway-auth-v2-inbound/doc.md

@@ -147,6 +147,64 @@ curl https://gateway.example.com/v1/chat/completions \
   }'
 ```
 
+## Pass through a caller's provider credential
+
+Set `credentialPassthrough` to `true` and configure a separate header for the
+Zuplo application key. For a bare key in `zp-gateway-api-key`, use these policy
+options:
+
+```json
+{
+  "credentialPassthrough": true,
+  "authHeader": "zp-gateway-api-key",
+  "authScheme": ""
+}
+```
+
+Send the provider credential in `Authorization`. `authHeader` and `authScheme`
+remain authoritative; sending a special header does not enable passthrough or
+override your configuration. The defaults remain `Authorization` and `Bearer`,
+so enabling passthrough without configuring a separate header is a configuration
+error.
+
+For example:
+
+```bash
+curl https://gateway.example.com/v1/chat/completions \
+  --header "zp-gateway-api-key: YOUR_ZUPLO_APP_KEY" \
+  --header "Authorization: Bearer YOUR_PROVIDER_CREDENTIAL" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "model": "provider/model",
+    "messages": [{ "role": "user", "content": "Hello" }]
+  }'
+```
+
+After the Zuplo application key succeeds, the policy moves the provider
+credential into private request-scoped state and removes both authentication
+headers from the mutable inbound request. The primary provider receives the
+original `Authorization` value exactly as supplied, instead of its configured
+credential. Retries of the primary use that same caller credential. Error and
+quota fallbacks use their own configured credentials, never the caller's token.
+Fallbacks therefore require configured credentials and can incur charges on the
+gateway owner's provider account. On native create requests at `/v1/messages`
+and `/v1/responses`, a compatible, explicitly configured backup runs only after
+the primary exhausts upstream 429 retries. It uses the backup's configured
+credential while preserving the native response and stream format; these
+endpoints do not use timeout, transport-error, or 5xx fallback. Semantic-cache
+policies skip passthrough requests so a cache hit cannot bypass upstream
+authentication. ZuploDemo is excluded because it must continue to use the
+gateway's deployment credential.
+
+A missing, empty, or invalid dedicated key fails authentication; the gateway
+never retries with `Authorization` as the Zuplo key. A missing or empty
+`Authorization` also returns 401 in this mode.
+
+With `credentialPassthrough` omitted or `false`, existing authentication
+applies: `authHeader` and `authScheme` select the Zuplo key, and providers use
+their configured credentials. Moving the gateway key to an arbitrary custom
+header alone does not enable passthrough.
+
 ## Choose a cache duration
 
 `cacheTtlSeconds` controls how long an authentication result can be reused. The
@@ -163,6 +221,10 @@ A revoked key can continue to work until its cached result expires.
 - `cacheTtlSeconds`: Number of seconds to cache an authentication result.
   Defaults to `10` and must be at least `10`.
 - `authHeader`: Header containing the application key. Defaults to
-  `Authorization`.
-- `authScheme`: Scheme before the key. Defaults to `Bearer`. Use `""` for a
-  header containing the key without a scheme.
+  `Authorization`. With `credentialPassthrough`, use a different header, such as
+  `zp-gateway-api-key`.
+- `authScheme`: Scheme before the key. Defaults to `Bearer`. Use `""` when the
+  header contains only the key.
+- `credentialPassthrough`: Forward the caller's `Authorization` header to the
+  primary provider as its credential while Zuplo reads the application key from
+  `authHeader`. Defaults to `false`.

package/docs/policies/ai-gateway-auth-v2-inbound/schema.json

@@ -12,7 +12,7 @@
   "requiresAI": true,
   "policyType": "ai-gateway-auth-v2",
   "products": ["ai-gateway"],
-  "description": "Authenticates requests to an AI Gateway endpoint with application API keys.\n\nAdd this policy to an application's `inboundPolicyChain` to require a key for that app only, or place it on the route before the configuration executor to require a key for every application on the route. The policies that follow can read the authenticated application from `request.user` (`sub` is the application name, `data` its metadata), and the application's AI Gateway configuration takes effect for the request. Use `authHeader` and `authScheme` when clients send their app key somewhere other than the default `Authorization: Bearer` header.\n\nWhen the matched route captures an `app_id` path parameter (platform catch-all `/:app_id/(.*)`), this policy also requires `configuration.id === request.params.app_id` and returns 403 on mismatch.",
+  "description": "Authenticates requests to an AI Gateway endpoint with application API keys.\n\nAdd this policy to an application's `inboundPolicyChain` to require a key for that app only, or place it on the route before the configuration executor to require a key for every application on the route. The policies that follow can read the authenticated application from `request.user` (`sub` is the application name, `data` its metadata), and the application's AI Gateway configuration takes effect for the request. Use `authHeader` and `authScheme` when clients send their app key somewhere other than the default `Authorization: Bearer` header. Enable `credentialPassthrough`, with the application key in a separate header, to forward the caller's `Authorization` header to the primary provider as its credential.\n\nWhen the matched route captures an `app_id` path parameter (platform catch-all `/:app_id/(.*)`), this policy also requires `configuration.id === request.params.app_id` and returns 403 on mismatch.",
   "deprecatedMessage": "",
   "required": ["handler"],
   "properties": {
@@ -36,6 +36,25 @@
           "description": "The options for this policy.",
           "additionalProperties": false,
           "required": [],
+          "if": {
+            "required": ["credentialPassthrough"],
+            "properties": {
+              "credentialPassthrough": {
+                "const": true
+              }
+            }
+          },
+          "then": {
+            "required": ["authHeader"],
+            "properties": {
+              "authHeader": {
+                "minLength": 1,
+                "not": {
+                  "pattern": "^\\s*[Aa][Uu][Tt][Hh][Oo][Rr][Ii][Zz][Aa][Tt][Ii][Oo][Nn]\\s*$"
+                }
+              }
+            }
+          },
           "properties": {
             "cacheTtlSeconds": {
               "type": "number",
@@ -48,14 +67,19 @@
               "default": "Authorization",
               "x-show-example": false,
               "x-advanced": true,
-              "description": "The name of the header with the key."
+              "description": "The request header that carries the Zuplo application key. When credentialPassthrough is enabled, use a header other than Authorization, such as zp-gateway-api-key."
             },
             "authScheme": {
               "type": "string",
               "default": "Bearer",
               "x-show-example": false,
               "x-advanced": true,
-              "description": "The scheme used on the header."
+              "description": "The scheme that prefixes the key in the authHeader header, for example Bearer. Set to an empty string when the header contains only the key."
+            },
+            "credentialPassthrough": {
+              "type": "boolean",
+              "default": false,
+              "description": "Forward the caller's Authorization header to the primary provider as its credential. Zuplo reads the application key from authHeader, which must be a header other than Authorization."
             }
           }
         }
@@ -65,7 +89,8 @@
           "export": "AIGatewayAuthV2InboundPolicy",
           "module": "$import(@zuplo/runtime)",
           "options": {
-            "cacheTtlSeconds": 10
+            "cacheTtlSeconds": 10,
+            "credentialPassthrough": false
           }
         }
       ]