zuplo 7.7.9 → 7.7.10

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

@@ -111,19 +111,53 @@ resource serves Claude on either host family the provider accepts.
 | ---------------------- | ------------------------ | ------------- |
 | `/v1/chat/completions` | ✅ Forwarded             | ✅ Translated |
 | `/v1/embeddings`       | ✅ Embedding models      | ❌            |
-| `/v1/messages`         | ❌                       | ✅ Native     |
-| `/v1/responses`        | ❌                       | ❌            |
+| `/v1/messages`         | ❌                       | ✅ Forwarded  |
+| `/v1/responses`        | ✅ Models that serve it  | ❌            |
 
-Streaming (`stream: true`) works on chat completions and messages.
+**Forwarded** means the gateway sends your request on in the shape you wrote it.
+**Translated** means it converts between two API shapes, which limits you to the
+parameters listed below.
+
+Streaming (`stream: true`) works on chat completions, messages, and responses.
 
 The catalog carries three embedding models—`text-embedding-3-small`,
 `text-embedding-3-large` and `text-embedding-ada-002`—so `/v1/embeddings` works
 once you deploy one of them and map your deployment to it.
 
-`/v1/responses` isn't served for Azure AI, and a Responses request fails with a
-`400` error before any upstream call. Azure does serve a Responses API on its
-own endpoint; the gateway doesn't route to it yet. Use `/v1/chat/completions`
-instead.
+`/v1/responses` serves the OpenAI Responses API, buffered and streaming. Support
+is **per deployed model**, not per resource: Azure serves Responses for
+particular model and version combinations, and a deployment outside that set
+answers `400` with `The requested operation is unsupported`—which is what an
+embedding deployment on this endpoint returns. Check Azure's own Responses API
+model list for your model and version before relying on it.
+
+The management operations on a stored response are forwarded too:
+
+| Operation                            | Does                                  |
+| ------------------------------------ | ------------------------------------- |
+| `GET /v1/responses/{id}`             | Retrieves the response                |
+| `GET /v1/responses/{id}/input_items` | Lists the input items of one response |
+| `DELETE /v1/responses/{id}`          | Deletes the response                  |
+
+Two things they need. Send **`store: true`** on the create, since your resource
+serves them only for a response it kept. And because these requests carry no
+body, there is no `model` in them for the gateway to route on—it uses the app's
+first configured completions model instead, so the app needs a
+[Model Filtering](../policies/ai-gateway-model-filtering-v2-inbound.mdx) policy
+whose completions allow list **starts with an OpenAI-compatible Azure
+deployment**. Without one the gateway answers `400`, asking for preselected
+routing, before reaching Azure.
+
+A Claude deployment doesn't work in that first slot, even though the allow list
+accepts it—Claude doesn't serve Responses at all, so the request still fails.
+
+Azure also takes a moment to make a new response readable. A `GET` immediately
+after a create can return `404` before it settles, so retry rather than treating
+the first `404` as final.
+
+Claude deployments don't serve Responses, so a Claude model on this endpoint
+fails with a `400` error—use
+[`/v1/messages`](#call-claude-models-on-the-messages-api) for those.
 
 Claude models work on `/v1/chat/completions` through the gateway's translation
 to the Messages API, which supports the core chat parameters: `messages`,
@@ -334,20 +368,27 @@ different beta still gets an answer, without that feature.
 The `model` field in a response doesn't always say what you might expect, and
 what it says depends on the model you called.
 
-**Claude responses report your deployment name.** Every other response reports
-Azure's own model ID, which usually carries a version date the short name
-doesn't.
+**Claude models and `/v1/responses` report your deployment name.** Everything
+else reports Azure's own model ID, which usually carries a version date the
+short name doesn't.
 
 | Endpoint               | Deployment `my-gpt` / `my-embed` / `my-claude` serves | `model` in the response   |
 | ---------------------- | ----------------------------------------------------- | ------------------------- |
 | `/v1/chat/completions` | `gpt-4.1-mini`                                        | `gpt-4.1-mini-2025-04-14` |
+| `/v1/responses`        | `gpt-4.1-mini`                                        | `my-gpt`                  |
 | `/v1/embeddings`       | `text-embedding-3-small`                              | `text-embedding-3-small`  |
 | `/v1/messages`         | `claude-haiku-4-5`                                    | `my-claude`               |
 | `/v1/chat/completions` | `claude-haiku-4-5`                                    | `my-claude`               |
 
+The same deployment reports two different values depending on the endpoint you
+call it on: chat completions answers with Azure's dated ID, Responses with the
+name you gave the deployment. That's Azure's own behavior on each surface, not
+something the gateway changes.
+
 A Claude model reports your deployment name on both endpoints—the native
-Messages API and the chat completions translation—because the gateway builds
-those responses itself and echoes back the model you asked for.
+Messages API and the chat completions translation—but for a different reason:
+there the gateway builds the response itself and echoes back the model you asked
+for.
 
 One exception, if you stream Claude: the `message_start` event reports Azure's
 ID (`claude-haiku-4-5-20251001`) rather than your deployment name, because the
@@ -388,8 +429,23 @@ resources deploy Claude. Confirm the deployment exists and is Anthropic-format,
 and see [Deploying Claude on Foundry](#deploying-claude-on-foundry) for the
 requirements Azure applies to those deployments.
 
-**A `400` error names `/v1/responses`.** The gateway doesn't serve the Responses
-API for Azure AI. Use `/v1/chat/completions`.
+**A `400` error names `/v1/responses`.** Two different causes, and the message
+tells you which. If it names the provider or the endpoint, the deployment is a
+**Claude** one—Claude doesn't serve Responses, so call
+[`/v1/messages`](#call-claude-models-on-the-messages-api) instead, or
+`/v1/chat/completions` for the translated form. If it says
+`The requested operation is unsupported`, that came from Azure: the deployed
+model doesn't serve Responses. Support is per model and version, so check
+Azure's Responses API model list—an embedding deployment always fails this way.
+
+**A `400` asks for preselected routing.** You called `GET` or `DELETE` on a
+response, or listed its input items. Those requests carry no body, so there is
+no `model` for the gateway to route on and it falls back to the app's first
+configured completions model. Add a
+[Model Filtering](../policies/ai-gateway-model-filtering-v2-inbound.mdx) policy
+to the app with an **OpenAI-compatible** Azure deployment first in its
+completions allow list. A Claude deployment in that slot still fails, since
+Claude doesn't serve Responses.
 
 **A model in the picker fails at request time.** The picker lists the full Azure
 catalog, but a model only works once you deploy it in your resource, and model

package/docs/ai-gateway/bedrock-mantle.mdx

@@ -72,9 +72,13 @@ either way.
 | ---------------------- | ---------------------------- | ------------- |
 | `/v1/chat/completions` | ✅ Forwarded                 | ✅ Translated |
 | `/v1/responses`        | ✅ Models that serve it      | ❌            |
-| `/v1/messages`         | ❌                           | ✅ Native     |
+| `/v1/messages`         | ❌                           | ✅ Forwarded  |
 | `/v1/embeddings`       | ❌ Mantle has no such models | ❌            |
 
+**Forwarded** means the gateway sends your request on in the shape you wrote it.
+**Translated** means it converts between two API shapes, which limits you to the
+parameters listed below.
+
 Streaming (`stream: true`) works on all three serving endpoints.
 
 On the OpenAI-compatible side, endpoint support is per model, decided by AWS:

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/providers.mdx

@@ -38,7 +38,7 @@ The following capabilities are supported across providers:
 | Google                     | ✅               | ✅         | ❌        | ❌       |
 | Mistral                    | ✅               | ✅         | ❌        | ❌       |
 | xAI                        | ✅               | ✅         | ❌        | ❌       |
-| Azure AI                   | ✅               | ✅         | ❌        | ✅       |
+| Azure AI                   | ✅               | ✅         | ✅        | ✅       |
 | Bedrock Mantle             | ✅               | ❌         | ✅        | ✅       |
 | Vertex AI                  | ✅               | ✅         | ❌        | ✅       |
 | Zuplo Demo                 | ✅               | ❌         | ❌        | ❌       |
@@ -54,8 +54,12 @@ 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 Messages support needs a Microsoft Foundry resource, since Claude
-can't be deployed on an Azure OpenAI resource. Azure also addresses models by
+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).
@@ -76,8 +80,8 @@ name you give the provider configuration. See the
 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
-  and embeddings.
+- 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

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

@@ -67,5 +67,5 @@ list—so clients that can't set a model still work.
 | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `/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 [Bedrock Mantle](./bedrock-mantle.mdx) OpenAI-compatible models that serve it                                                 |
+| `/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.7.9",
+  "version": "7.7.10",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.7.9",
-    "@zuplo/core": "7.7.9",
-    "@zuplo/runtime": "7.7.9",
-    "@zuplo/test": "7.7.9"
+    "@zuplo/cli": "7.7.10",
+    "@zuplo/core": "7.7.10",
+    "@zuplo/runtime": "7.7.10",
+    "@zuplo/test": "7.7.10"
   }
 }