zuplo 7.9.5 → 7.9.8

package/docs/ai-gateway/apps.mdx

@@ -2,17 +2,27 @@
 title: AI Gateway Apps
 sidebar_label: Overview
 description:
-  Apps represent the services and integrations that call your AI Gateway. Each
-  app has its own URL, API key, and policy chain.
+  Apps are how software and people call your AI Gateway. Services use apps with
+  their own API keys; people use the User App with their own personal API key.
 ---
 
-An app represents one caller of your AI Gateway—a service, an agent, or a
-feature in a larger codebase. A support chatbot on your website is one app; the
-batch job that summarizes tickets overnight is another. Each app belongs to a
-[team](./teams.mdx), which controls dashboard access to the app. Access to AI
-providers is governed separately by the user's Zuplo account and Zuplo project
-roles. A Zuplo account contains one or more projects, and the AI Gateway is the
-Zuplo project that contains these providers, teams, and apps. See
+Everything that calls your AI Gateway goes through an app. There are two kinds:
+
+| Kind                            | Who calls it                                                     | Key                                | Budget                                           |
+| ------------------------------- | ---------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------ |
+| **App**                         | Software: a service, an agent, or a feature in a larger codebase | One API key per app                | The app's own, plus its pool's and the gateway's |
+| **[User App](./user-apps.mdx)** | People, from their everyday tools such as Claude Code or Codex   | Each person's own personal API key | Per person, plus the gateway's                   |
+
+A support chatbot on your website is one app; the batch job that summarizes
+tickets overnight is another. An engineer who wants to use Claude Code through
+the gateway doesn't need an app of their own: they create a personal key and
+call the project's [User App](./user-apps.mdx).
+
+The rest of this page covers apps. Each app belongs to a [pool](./pools.mdx),
+which groups apps and controls dashboard access to them. Access to AI providers
+is governed separately by the user's Zuplo account and Zuplo project roles. A
+Zuplo account contains one or more projects, and the AI Gateway is the Zuplo
+project that contains these providers, pools, and apps. See
 [Role Permissions](../articles/accounts/roles-and-permissions.mdx).
 
 Each app has three things of its own:
@@ -28,7 +38,7 @@ Each app has three things of its own:
   [authentication policy](./policy-chains.mdx#authentication).
 - **A [policy chain](./policy-chains.mdx)**—the ordered policies that run on the
   app's requests: model access, app-specific budgets, caching, guardrails, and
-  custom policies. The chain starts out empty unless the app's team has a
+  custom policies. The chain starts out empty unless the app's pool has a
   [policy template](./policy-templates.mdx).
 
 ## API Keys
@@ -40,14 +50,14 @@ validated key or from the `{app_id}` segment of the request URL, so an app
 without authentication still tracks usage independently.
 
 To find an app's API key, open the
-[Apps & Teams](https://portal.zuplo.com/+/account/project/ai/apps) tab of your
-AI Gateway project in the Zuplo Portal and select the app. The key lives on the
+[Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab of your AI
+Gateway project in the Zuplo Portal and select the app. The key lives on the
 app's **API Key** tab.
 
 :::caution{title="Rotate keys to revoke access"}
 
 An issued app API key authenticates gateway traffic by the key itself. Changing
-a user's dashboard permissions or removing them from a team doesn't invalidate
+a user's dashboard permissions or removing them from a pool doesn't invalidate
 the key. To revoke access, rotate the app's API key and update authorized
 clients with the new value.
 
@@ -57,7 +67,9 @@ clients with the new value.
 
 - [Creating & Editing Apps](./managing-apps.mdx) - How to create, configure, and
   delete apps.
-- [Creating & Editing Teams](./managing-teams.mdx) - How to create and edit
-  teams.
+- [User Apps](./user-apps.mdx) - How people call the gateway with a personal API
+  key.
+- [Creating & Editing Pools](./managing-pools.mdx) - How to create and edit
+  pools.
 - [Role Permissions](../articles/accounts/roles-and-permissions.mdx) - Details
-  on Zuplo account, Zuplo project, and AI Gateway team roles.
+  on Zuplo account, Zuplo project, and AI Gateway pool roles.

package/docs/ai-gateway/custom-policies.mdx

@@ -11,7 +11,7 @@ The AI Gateway's built-in policies cover model access, app-specific budgets,
 caching, guardrails, and tracing—but your gateway can run any policy you can
 write in TypeScript. A custom policy lives in your gateway's
 [repository](./source-control.mdx), is declared in `config/policies.json`, and
-from then on appears in the portal's **Add Policy** dialog like any built-in
+from then on appears in the portal's **Add policy** dialog like any built-in
 policy. Apps add it to their [policy chains](./policy-chains.mdx), and it runs
 on every request for those apps.
 
@@ -21,7 +21,7 @@ terms. By the end, one app on your gateway rejects a prompt containing
 
 ## Prerequisites
 
-- An AI Gateway project connected to a Git repository, with a provider, a team,
+- An AI Gateway project connected to a Git repository, with a provider, a pool,
   and an app—the [Getting Started](../getting-started/ai-gateway/portal.mdx)
   guide covers this
 - A local clone of the gateway's repository
@@ -118,10 +118,10 @@ terms. By the end, one app on your gateway rejects a prompt containing
 4. **Add the policy to an app's chain**
 
    In the Zuplo Portal, open
-   [**Apps & Teams**](https://portal.zuplo.com/+/account/project/ai/apps),
-   select your app, and open its **Policies** tab. Click **Add
-   Policy**—`content-filter` now appears alongside the built-in policies. Add
-   it, drag it to where in the chain it should run, and save.
+   [**Apps**](https://portal.zuplo.com/+/account/project/ai/apps), select your
+   app, and open its **Policies** tab. Click **Add policy**—`content-filter` now
+   appears alongside the built-in policies. Add it, drag it to where in the
+   chain it should run, and save.
 
    :::tip{title="Where in the chain?"}
 
@@ -214,5 +214,5 @@ complete recipes:
 - [Policy Chains](./policy-chains.mdx): execution order, options inheritance,
   and the built-in policies
 - [Policy Templates](./policy-templates.mdx): roll a custom policy out to every
-  new app in a team
+  new app in a pool
 - [Source Control](./source-control.mdx): how repository changes deploy

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

@@ -59,7 +59,7 @@ To add a custom AI provider to your Zuplo AI Gateway, follow these steps:
    reserves the built-in provider names (`openai`, `anthropic`, `google`,
    `mistral`, `xai`, `moonshot`, `zuplo`, `zuplodemo`, `zuplo-demo`,
    `bedrockmantle`, `bedrock-mantle`, `azureai`, `azure-ai`, `vertexai`,
-   `vertex-ai`, `openrouter`, `open-router`). The name is permanent after
+   `vertex-ai`, `openrouter`, `open-router`, `jev`). The name is permanent after
    creation.
 
 1. Enter the provider's **API URL** as its origin root—for example

package/docs/ai-gateway/fallback.mdx

@@ -17,7 +17,7 @@ different condition:
 | Mechanism              | Triggers when…                                                                                         | Without a fallback set…                     |
 | ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
 | **Fallback & Timeout** | The primary fails with a retryable error (`5xx`, `408`, `425`, `429`), a network failure, or a timeout | The gateway returns the error to the caller |
-| **Quota Fallback**     | An app, team, or gateway usage limit is exceeded                                                       | The request is blocked with a `429`         |
+| **Quota Fallback**     | An app, pool, or gateway usage limit is exceeded                                                       | The request is blocked with a `429`         |
 
 Both are configured entirely in the Zuplo Portal, and either can route to _any_
 provider—the fallback doesn't have to share the primary's provider. Fallback
@@ -27,11 +27,11 @@ models are referenced like any model, as `providerName/model`.
 
 <Stepper>
 
-1. Open the [Apps & Teams](https://portal.zuplo.com/+/account/project/ai/apps)
-   tab of your AI Gateway project and select the app to edit.
+1. Open the [Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab of
+   your AI Gateway project and select the app to edit.
 
 1. Select the **Policies** tab. If the chain doesn't have a **Fallback Model**
-   policy yet, click **Add Policy** and add it—placed directly after Model
+   policy yet, click **Add policy** and add it—placed directly after Model
    Filtering.
 
 1. Configure the policy:
@@ -57,7 +57,7 @@ is configured, the primary model call runs unbounded.
 ## Quota fallback
 
 For requests continuing to a provider, the quota fallback selects an alternate,
-usually cheaper, model when an app, team, or gateway
+usually cheaper, model when an app, pool, or gateway
 [usage limit](./usage-limits.mdx) is exceeded, rather than blocking the request
 with a `429`. This keeps an app available after an applicable budget, token, or
 request threshold is crossed, while shifting the overflow traffic to a

package/docs/ai-gateway/integrations/ai-sdk.mdx

@@ -22,10 +22,10 @@ complete these steps first:
 1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for the
    provider you want to use with AI SDK
 
-2. [Set up a new team](../managing-teams.mdx)
+2. [Set up a new pool](../managing-pools.mdx)
 
 3. Create a [new app](../managing-apps.mdx) to use specifically with AI SDK and
-   assign it to the team you created
+   assign it to the pool you created
 
 4. Copy the **API URL** and **API Key** shown at the top of the app page
 

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

@@ -2,8 +2,8 @@
 title: Claude Code
 sidebar_label: Claude Code
 description:
-  Route Claude Code requests through a Zuplo AI Gateway app, with a provider key
-  or your Claude subscription.
+  Route Claude Code through the Zuplo AI Gateway with your personal API key or
+  an app's API key, using either a provider key or your Claude subscription.
 ---
 
 Route [Claude Code](https://www.claude.com/product/claude-code) through the
@@ -11,27 +11,27 @@ Zuplo AI Gateway. The gateway authenticates, meters, and routes every session.
 
 The gateway authenticates to Anthropic in one of two ways:
 
-| Approach                                             | The gateway sends Anthropic                       | Claude Code sends the gateway                                       |
-| ---------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
-| [Provider key](#use-a-provider-key)                  | The Anthropic API key saved on your provider      | The app's API key as `ANTHROPIC_AUTH_TOKEN`                         |
-| [Claude subscription](#use-your-claude-subscription) | 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 |
+| Approach                                             | The gateway sends Anthropic                       | Claude Code sends the gateway                                         |
+| ---------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------- |
+| [Provider key](#use-a-provider-key)                  | The Anthropic API key saved on your provider      | Your personal API key, or an app's API key, as `ANTHROPIC_AUTH_TOKEN` |
+| [Claude subscription](#use-your-claude-subscription) | Your `claude.ai` login, such as a Claude Max plan | An app's API key in a `zp-gateway-api-key` header, plus your login    |
 
 ## Prerequisites
 
-<Stepper>
-
-1. Create an Anthropic [provider](../managing-providers.mdx) in the AI Gateway.
-
-2. [Create a team](../managing-teams.mdx). For the subscription approach,
-   [configure its API Key Authentication policy](#configure-the-api-key-authentication-policy)
-   now.
-
-3. [Create an app](../managing-apps.mdx) for Claude Code and assign it to the
-   team.
+Create an Anthropic [provider](../managing-providers.mdx) in the AI Gateway,
+then get a gateway URL and key in one of two ways:
 
-4. Copy the **API URL** and **API Key** from the app page.
+- **Use your personal API key (recommended).** Claude Code runs on your own
+  machine, so call the project's [User App](../user-apps.mdx). Open the
+  [**Home**](https://portal.zuplo.com/+/account/project/ai/home) tab of your AI
+  Gateway project, copy the **Gateway URL**, and create a key under **My API
+  keys**. Your requests count against your own budget.
+- **Use an app.** For a shared or automated setup, and for the
+  [Claude subscription](#use-your-claude-subscription) approach,
+  [create a pool](../managing-pools.mdx) and [an app](../managing-apps.mdx) for
+  Claude Code, then copy the app's **API URL** and **API Key**.
 
-</Stepper>
+The rest of this guide calls these your **gateway URL** and **gateway key**.
 
 ## Configure Claude Code
 
@@ -51,27 +51,29 @@ project. Add the block for your approach, then restart Claude Code.
 
 ### Rules
 
-- `ANTHROPIC_BASE_URL` is the app's API URL _without_ `/v1`. Claude Code appends
+- `ANTHROPIC_BASE_URL` is your gateway URL _without_ `/v1`. Claude Code appends
   `/v1/messages`.
 - Set every `ANTHROPIC_*_MODEL` variable and every `modelOverrides` entry.
   Claude Code's built-in model names have no prefix. The variables map the
   `opus`, `sonnet`, `haiku`, and `fable` aliases;
   [`modelOverrides`](https://code.claude.com/docs/en/model-config#override-model-ids-per-version)
   maps exact IDs; the `/model` picker can select either.
-- The app's
-  [Model Filtering](../../policies/ai-gateway-model-filtering-inbound.mdx)
-  policy controls which models the app can use.
+- The [Model Filtering](../../policies/ai-gateway-model-filtering-inbound.mdx)
+  policy on the User App or the app controls which models you can use.
 
 ## Use a provider key
 
 The gateway calls Anthropic with the key saved on your provider. Anthropic bills
 that key's account. Your Claude subscription is not used.
 
+This example uses a personal API key and the User App's gateway URL. For an app,
+use the app's API key and API URL instead.
+
 ```json
 {
   "env": {
-    "ANTHROPIC_AUTH_TOKEN": "<your-ai-gateway-app-api-key>",
-    "ANTHROPIC_BASE_URL": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e",
+    "ANTHROPIC_AUTH_TOKEN": "<your-personal-api-key>",
+    "ANTHROPIC_BASE_URL": "https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64",
     "ANTHROPIC_MODEL": "anthropic/claude-sonnet-5",
     "ANTHROPIC_SMALL_FAST_MODEL": "anthropic/claude-haiku-4-5",
     "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5",
@@ -93,13 +95,17 @@ that key's account. Your Claude subscription is not used.
 
 ## Use your Claude subscription
 
+This approach is shown with an app. On the User App, turning on passthrough
+would change authentication for everyone who uses it, so use an app for
+subscription logins.
+
 Claude Code stays signed in to `claude.ai`. The gateway forwards that login to
 Anthropic and reads the app's API key from a separate `zp-gateway-api-key`
 header, so it still authenticates the app, runs its policies, and meters usage.
 
 ### Configure the API Key Authentication policy
 
-On the team's [policy template](../policy-templates.mdx), or on one app's
+On the pool's [policy template](../policy-templates.mdx), or on one app's
 **Policies** tab, edit **API Key Authentication**:
 
 <Stepper>
@@ -177,15 +183,17 @@ claude -p "Reply with the single word OK"
 ```
 
 With the subscription approach, the first command reports a `claude.ai` login,
-not an API key or auth token. The request appears in the app's usage in the
+not an API key or auth token. With a personal key, the request appears in your
+usage on the **Home** tab; with an app, it appears in the app's usage in the
 Zuplo Portal.
 
 ## Troubleshooting
 
-| Error                                                                   | Fix                                                                                                                                        |
-| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `400` `model must use "providerName/model"`                             | The selected model has no provider prefix. Check `ANTHROPIC_MODEL`, or the picker entry's `modelOverrides` mapping. Restart after editing. |
-| `401` `Invalid Authorization Scheme`                                    | `authScheme` still has its `Bearer` default. Set an explicit empty value.                                                                  |
-| `401` `Header configured by options.authHeader is missing`              | Claude Code didn't send `zp-gateway-api-key`. Check `ANTHROPIC_CUSTOM_HEADERS`.                                                            |
-| `401` `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. Sign in to Claude Code again.                                                                      |
+| Error                                                                            | Fix                                                                                                                                                                                   |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` `model must use "providerName/model"`                                      | The selected model has no provider prefix. Check `ANTHROPIC_MODEL`, or the picker entry's `modelOverrides` mapping. Restart after editing.                                            |
+| `403` `This User App route requires a personal API key issued for this User App` | With a personal key: the key is missing, wrong, from another project, or not sent as `Authorization: Bearer`. Create a key on **Home** and use the Gateway URL from the same project. |
+| `401` `Invalid Authorization Scheme`                                             | `authScheme` still has its `Bearer` default. Set an explicit empty value.                                                                                                             |
+| `401` `Header configured by options.authHeader is missing`                       | Claude Code didn't send `zp-gateway-api-key`. Check `ANTHROPIC_CUSTOM_HEADERS`.                                                                                                       |
+| `401` `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. Sign in to Claude Code again.                                                                                                                 |

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

@@ -2,8 +2,8 @@
 title: Claude Desktop
 sidebar_label: Claude Desktop
 description:
-  Route Claude Desktop's Chat, Cowork, and Code sessions through a Zuplo AI
-  Gateway app.
+  Route Claude Desktop's Chat, Cowork, and Code sessions through the Zuplo AI
+  Gateway with your personal API key, or with an app's key for a managed fleet.
 ---
 
 Route [Claude Desktop](https://claude.com/download) through the Zuplo AI
@@ -15,18 +15,20 @@ To give Claude Desktop tools from a Zuplo MCP route instead, see
 
 ## Prerequisites
 
-<Stepper>
-
-1. Create an Anthropic [provider](../managing-providers.mdx) in the AI Gateway.
-
-2. [Create a team](../managing-teams.mdx).
+Create an Anthropic [provider](../managing-providers.mdx) in the AI Gateway,
+then get a gateway URL and key in one of two ways:
 
-3. [Create an app](../managing-apps.mdx) for Claude Desktop and assign it to the
-   team.
+- **Use your personal API key (recommended).** Claude Desktop runs on your own
+  machine, so call the project's [User App](../user-apps.mdx). Open the
+  [**Home**](https://portal.zuplo.com/+/account/project/ai/home) tab of your AI
+  Gateway project, copy the **Gateway URL**, and create a key under **My API
+  keys**. Your requests count against your own budget.
+- **Use an app.** For a shared setup, such as
+  [deploying to a fleet](#deploy-to-a-fleet) with one key,
+  [create a pool](../managing-pools.mdx) and [an app](../managing-apps.mdx) for
+  Claude Desktop, then copy the app's **API URL** and **API Key**.
 
-4. Copy the **API URL** and **API Key** from the app page.
-
-</Stepper>
+The rest of this guide calls these your **gateway URL** and **gateway key**.
 
 ## Configure Claude Desktop
 
@@ -39,16 +41,15 @@ To give Claude Desktop tools from a Zuplo MCP route instead, see
 
 3. Under **Connection**, set **Inference provider** to **Gateway**.
 
-4. Under **Gateway credentials**, set **Gateway base URL** to the app's API URL,
+4. Under **Gateway credentials**, set **Gateway base URL** to your gateway URL,
    for example
-   `https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e`,
-   and **Gateway API key** to the app's API key.
+   `https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64`,
+   and **Gateway API key** to your gateway key.
 
 5. Leave **Credential kind** set to **Static API key** and **Gateway auth
    scheme** set to **Bearer**.
 
-6. Under **Models**, add each model the app may use. See
-   [Add models](#add-models).
+6. Under **Models**, add each model you may use. See [Add models](#add-models).
 
 7. Click **Apply locally**. Claude Desktop saves the configuration and
    relaunches.
@@ -57,12 +58,12 @@ To give Claude Desktop tools from a Zuplo MCP route instead, see
 
 ### Rules
 
-- **Gateway base URL** is the app's API URL _without_ `/v1`. Claude Desktop
+- **Gateway base URL** is your gateway URL _without_ `/v1`. Claude Desktop
   appends `/v1/messages`.
 - **Gateway auth scheme** stays **Bearer**. The gateway reads the API key from
   the `Authorization: Bearer` header.
-- **Credential kind** stays **Static API key**. AI Gateway apps authenticate
-  with API keys, not identity-provider tokens.
+- **Credential kind** stays **Static API key**. The AI Gateway authenticates
+  with personal or app API keys, not identity-provider tokens.
 
 ## Add models
 
@@ -92,28 +93,30 @@ Click **Add** once per model:
 The first entry is the picker default. Include a Haiku-tier model: Claude
 Desktop runs background and sub-agent tasks on a small, fast model.
 
-The app's
-[Model Filtering](../../policies/ai-gateway-model-filtering-inbound.mdx) policy
-controls which models the app can use.
+The [Model Filtering](../../policies/ai-gateway-model-filtering-inbound.mdx)
+policy on the User App or the app controls which models you can use.
 
 ## Verify
 
-Send a message in Chat and start a Cowork session. Both appear in the app's
-usage in the Zuplo Portal, as do Code sessions started from the desktop app.
-Terminal Claude Code sessions use their own configuration. See
-[Claude Code](./claude-code.mdx).
+Send a message in Chat and start a Cowork session. Both appear in your usage on
+the **Home** tab, or in the app's usage if you used an app, as do Code sessions
+started from the desktop app. Terminal Claude Code sessions use their own
+configuration. See [Claude Code](./claude-code.mdx).
 
 ## Troubleshooting
 
-| Error                                                        | Fix                                                                                         |
-| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
-| `400` `The request body model must use "providerName/model"` | A model list entry has no provider prefix. Give every entry a full `providerName/model` ID. |
+| Error                                                                            | Fix                                                                                                                                                                                   |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` `The request body model must use "providerName/model"`                     | A model list entry has no provider prefix. Give every entry a full `providerName/model` ID.                                                                                           |
+| `403` `This User App route requires a personal API key issued for this User App` | With a personal key: the key is missing, wrong, from another project, or not sent as `Authorization: Bearer`. Create a key on **Home** and use the Gateway URL from the same project. |
 
 ## Deploy to a fleet
 
-Use the configuration window's **Export** menu instead of **Apply locally**. It
-produces a `.mobileconfig` profile for macOS MDM tools such as Jamf, a `.reg`
-policy file for Intune or Group Policy, and related artifacts. Managed
-configuration overrides local settings. See Anthropic's
+A fleet deployment shares one gateway key across machines, so use an app's API
+URL and API key rather than a personal key. Use the configuration window's
+**Export** menu instead of **Apply locally**. It produces a `.mobileconfig`
+profile for macOS MDM tools such as Jamf, a `.reg` policy file for Intune or
+Group Policy, and related artifacts. Managed configuration overrides local
+settings. See Anthropic's
 [Deploy Claude Desktop with an LLM gateway](https://claude.com/docs/third-party/claude-desktop/gateway)
 and [Deploy with MDM](https://claude.com/docs/third-party/claude-desktop/mdm).

package/docs/ai-gateway/integrations/codex.mdx

@@ -1,7 +1,9 @@
 ---
 title: Codex
 sidebar_label: Codex
-description: Route Codex CLI requests through a Zuplo AI Gateway app.
+description:
+  Route Codex CLI requests through the Zuplo AI Gateway with your personal API
+  key or an app's API key, using a provider key or your ChatGPT subscription.
 ---
 
 [Codex](https://developers.openai.com/codex) is OpenAI's coding agent for the
@@ -12,24 +14,25 @@ Two approaches:
 - **Use a provider key.** The gateway calls OpenAI with the API key saved on
   your provider. OpenAI bills that key's account.
 - **Use your ChatGPT subscription.** Codex stays signed in with `codex login`.
-  The gateway forwards that login to OpenAI and meters usage against your app.
+  The gateway forwards that login to OpenAI and meters usage against an app.
   Your ChatGPT plan pays for the tokens.
 
 ## Prerequisites
 
-<Stepper>
+Create an OpenAI [provider](../managing-providers.mdx) in the AI Gateway, then
+get a gateway URL and key in one of two ways:
 
-1. Create an OpenAI [provider](../managing-providers.mdx) in the AI Gateway.
+- **Use your personal API key (recommended).** Codex runs on your own machine,
+  so call the project's [User App](../user-apps.mdx). Open the
+  [**Home**](https://portal.zuplo.com/+/account/project/ai/home) tab of your AI
+  Gateway project, copy the **Gateway URL**, and create a key under **My API
+  keys**. Your requests count against your own budget.
+- **Use an app.** For a shared or automated setup, and for the
+  [ChatGPT subscription](#use-your-chatgpt-subscription) approach,
+  [create a pool](../managing-pools.mdx) and [an app](../managing-apps.mdx) for
+  Codex, then copy the app's **API URL** and **API Key**.
 
-2. [Create a team](../managing-teams.mdx). For the subscription approach,
-   [configure its API Key Authentication policy](#configure-the-api-key-authentication-policy)
-   now.
-
-3. [Create an app](../managing-apps.mdx) for Codex and assign it to the team.
-
-4. Copy the **API URL** and **API Key** from the app page.
-
-</Stepper>
+The rest of this guide calls these your **gateway URL** and **gateway key**.
 
 ## Configure Codex
 
@@ -47,27 +50,34 @@ Codex reads configuration from `~/.codex/config.toml`. Create this file (and the
 approach, then set the API key in your environment and restart Codex:
 
 ```bash
-export ZUPLO_AI_GATEWAY_API_KEY="<your-app-api-key>"
+export ZUPLO_AI_GATEWAY_API_KEY="<your-gateway-key>"
 ```
 
 ### Use a provider key
 
+This example uses the User App's gateway URL. For an app, use the app's API URL
+instead.
+
 ```toml
 model_provider = "zuplo"
 model = "openai/gpt-5"
 
 [model_providers.zuplo]
 name = "Zuplo AI Gateway"
-base_url = "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1"
+base_url = "https://my-gateway-main-2e18f50.zuplo.app/u/741d375d631b429293481d6d0458bb64/v1"
 env_key = "ZUPLO_AI_GATEWAY_API_KEY"
 wire_api = "responses"
 ```
 
-- `base_url` is the app's API URL with `/v1` appended.
+- `base_url` is your gateway URL with `/v1` appended.
 - `model` is `providerName/model`.
 
 ### Use your ChatGPT subscription
 
+This approach is shown with an app. On the User App, turning on passthrough
+would change authentication for everyone who uses it, so use an app for
+subscription logins.
+
 ```toml
 model_provider = "zuplo"
 model = "openai/gpt-5.6-sol"
@@ -92,7 +102,7 @@ login anywhere except OpenAI, and never sends your app key to OpenAI.
 
 #### Configure the API Key Authentication policy
 
-On the team's [policy template](../policy-templates.mdx), or on the app's
+On the pool's [policy template](../policy-templates.mdx), or on the app's
 **Policies** tab, edit **API Key Authentication** in the **JSON** editor:
 
 ```json
@@ -137,9 +147,8 @@ prefix, and the gateway rejects them with a `400`.
 Codex warns that it has no metadata for a prefixed model name. Requests still
 succeed.
 
-The app's
-[Model Filtering](../../policies/ai-gateway-model-filtering-inbound.mdx) policy
-controls which models the app can use.
+The [Model Filtering](../../policies/ai-gateway-model-filtering-inbound.mdx)
+policy on the User App or the app controls which models you can use.
 
 ## Verify
 
@@ -147,18 +156,20 @@ controls which models the app can use.
 codex exec "Reply with the single word OK"
 ```
 
-The session header shows `provider: zuplo`. The request appears in the app's
+The session header shows `provider: zuplo`. With a personal key, the request
+appears in your usage on the **Home** tab; with an app, it appears in the app's
 usage in the Zuplo Portal.
 
 ## Troubleshooting
 
-| Error                                                                                      | Fix                                                                                           |
-| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| `400` `The request body model must use "providerName/model"`                               | Add the provider prefix to `model`. Do not use the `/model` picker.                           |
-| `ERROR: Missing environment variable: ZUPLO_AI_GATEWAY_API_KEY`                            | Export the variable in the shell that runs Codex.                                             |
-| `401` `Authorization Failed`                                                               | The API key is wrong. Copy it from the app's **API Key** tab.                                 |
-| `401` `Header configured by options.authHeader is missing`                                 | Subscription approach: add the `env_http_headers` line and export `ZUPLO_AI_GATEWAY_API_KEY`. |
-| `401` `Invalid Authorization Scheme`                                                       | Set `authScheme` to the empty string in the policy JSON.                                      |
-| `401` `rejected the credential this app passed through from the caller` `(HTTP 401)`       | Your ChatGPT login expired or is invalid. Run `codex login` again.                            |
-| `401` `Missing scopes: api.responses.write`                                                | The app is not in passthrough mode. Configure the API Key Authentication policy as above.     |
-| Errors mention `api.openai.com` or `not supported when using Codex with a ChatGPT account` | Codex is not using your provider. Set `model_provider = "zuplo"`.                             |
+| Error                                                                                      | Fix                                                                                                                                                                                   |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` `The request body model must use "providerName/model"`                               | Add the provider prefix to `model`. Do not use the `/model` picker.                                                                                                                   |
+| `403` `This User App route requires a personal API key issued for this User App`           | With a personal key: the key is missing, wrong, from another project, or not sent as `Authorization: Bearer`. Create a key on **Home** and use the Gateway URL from the same project. |
+| `ERROR: Missing environment variable: ZUPLO_AI_GATEWAY_API_KEY`                            | Export the variable in the shell that runs Codex.                                                                                                                                     |
+| `401` `Authorization Failed`                                                               | With an app: the key is wrong. Copy it from the app's **API Key** tab.                                                                                                                |
+| `401` `Header configured by options.authHeader is missing`                                 | Subscription approach: add the `env_http_headers` line and export `ZUPLO_AI_GATEWAY_API_KEY`.                                                                                         |
+| `401` `Invalid Authorization Scheme`                                                       | Set `authScheme` to the empty string in the policy JSON.                                                                                                                              |
+| `401` `rejected the credential this app passed through from the caller` `(HTTP 401)`       | Your ChatGPT login expired or is invalid. Run `codex login` again.                                                                                                                    |
+| `401` `Missing scopes: api.responses.write`                                                | The app is not in passthrough mode. Configure the API Key Authentication policy as above.                                                                                             |
+| Errors mention `api.openai.com` or `not supported when using Codex with a ChatGPT account` | Codex is not using your provider. Set `model_provider = "zuplo"`.                                                                                                                     |