zuplo 7.6.1 → 7.6.3

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

@@ -51,9 +51,11 @@ To add a new AI provider to your Zuplo AI Gateway, follow these steps:
    create an API key for each provider see the
    [provider documentation](./providers.mdx). The
    [Zuplo Demo provider](./providers.mdx#zuplo-demo) asks for no API key—your
-   gateway authenticates to the demo service itself, and
+   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.
+   Region** and accepts only long-term Bedrock API keys, and
+   [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.
 
 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.
@@ -83,10 +85,12 @@ 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. 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.
+[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
+reference to this provider. After making your changes, click **Save** to apply
+them.
 
 :::caution
 

package/docs/ai-gateway/{introduction.mdx → overview.mdx}

@@ -1,6 +1,6 @@
 ---
-title: Zuplo AI Gateway
-sidebar_label: Introduction
+title: AI Gateway overview
+sidebar_label: Overview
 description:
   The Zuplo AI Gateway is a proxy between your apps and LLM providers, deployed
   from your own Git repository, with per-app policy pipelines for cost control,
@@ -76,11 +76,11 @@ usage limits still apply.
 
 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)), 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 `openai/gpt-5-mini`—so a single app can use models from several
-providers.
+(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
+`openai/gpt-5-mini`—so a single app can use models from several providers.
 
 ### Source-Controlled Gateway
 

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

@@ -1,5 +1,5 @@
 ---
-title: AI Gateway policies
+title: AI Gateway policies overview
 sidebar_label: Overview
 description: Every policy an AI Gateway app can run, and what each one does.
 ---

package/docs/ai-gateway/providers.mdx

@@ -3,8 +3,8 @@ title: AI Providers
 sidebar_label: Overview
 description:
   The AI providers and capabilities the Zuplo AI Gateway supports, including
-  OpenAI, Anthropic, Google, Mistral, xAI, and OpenAI-compatible custom
-  providers.
+  OpenAI, Anthropic, Google, Vertex AI, Mistral, xAI, and OpenAI-compatible
+  custom providers.
 ---
 
 Zuplo's AI Gateway supports integration with various AI providers, allowing you
@@ -21,6 +21,8 @@ Zuplo currently supports the following AI providers:
 - xAI (Grok)
 - [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
+  Gemini and Model Garden models on your own Google Cloud project
 - [Zuplo Demo](#zuplo-demo)—a free, keyless provider for trying the gateway
 - OpenAI-compatible [Custom Providers](./custom-providers.mdx) (such as Qwen,
   Kimi, etc)
@@ -35,6 +37,7 @@ The following capabilities are supported across providers:
 | Mistral                    | ✅               | ✅         | ❌        | ❌       |
 | xAI                        | ✅               | ✅         | ❌        | ❌       |
 | Bedrock Mantle             | ✅               | ❌         | ✅        | ✅       |
+| Vertex AI                  | ✅               | ✅         | ❌        | ❌       |
 | Zuplo Demo                 | ✅               | ❌         | ❌        | ❌       |
 | OpenAI-compatible (Custom) | ✅               | ✅         | ❌        | ❌       |
 
@@ -77,6 +80,32 @@ instead of an endpoint URL, and it accepts only long-term Bedrock API keys,
 which start with `ABSK`. For prerequisites, setup steps, code examples, and
 troubleshooting, see [Using Bedrock Mantle](./bedrock-mantle.mdx).
 
+## Vertex AI
+
+**Vertex AI** is Google Cloud's managed model platform. One provider
+configuration serves both the Gemini family and Vertex's Model Garden partner
+models—DeepSeek, Qwen, GLM, Kimi, MiniMax, Gemma, and GPT-OSS—from your own
+Google Cloud project, on your Google Cloud billing.
+
+Two things make its setup different from every other provider:
+
+- **It authenticates with a service account, not an API key.** Vertex's
+  prediction endpoints reject API keys, so the dialog asks for a service account
+  JSON key file and the gateway exchanges it for short-lived access tokens.
+- **It needs a Google Cloud project as well as a location.** Vertex endpoints
+  are per-location, and the project isn't part of the endpoint, so the dialog
+  asks for both.
+
+Every Vertex model ID is publisher-qualified, so a model reference has two
+slashes: a provider named `vertexai` serves `vertexai/google/gemini-3.7-flash`
+and `vertexai/qwen/qwen3-coder-480b-a35b-instruct-maas`. Model availability
+varies by location—most Model Garden models are served only from the `global`
+location. Vertex also hosts Anthropic's Claude models, but on a different API
+surface that the gateway doesn't route to.
+
+For prerequisites, Google Cloud setup, provider steps, code examples, and
+troubleshooting, see [Using Vertex AI](./vertex-ai.mdx).
+
 ## Zuplo Demo
 
 **Zuplo Demo** is a free provider that Zuplo operates so you can try the AI

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

@@ -0,0 +1,389 @@
+---
+title: Using Vertex AI
+sidebar_label: Vertex AI
+description:
+  Serve Gemini and Model Garden models from your own Google Cloud project
+  through one provider configuration—one Vertex AI location, one project ID, and
+  one service account key. The gateway mints and refreshes the access tokens
+  Vertex requires.
+---
+
+**Vertex AI** is Google Cloud's managed model platform. Adding it as a provider
+serves both the Gemini family and Vertex's Model Garden partner models—DeepSeek,
+Qwen, GLM, Kimi, MiniMax, Gemma, and GPT-OSS—to your [apps](./apps.mdx) through
+the [Universal API](./universal-api.mdx), running on your Google Cloud project
+and your Google Cloud billing.
+
+Chat completions go to Vertex's **OpenAI-compatible endpoint**, so the gateway
+forwards OpenAI-shaped requests without translating them. Embeddings work too,
+though Vertex has no OpenAI-compatible embeddings endpoint—the gateway
+translates those onto Vertex's own embedding APIs, which is invisible from your
+app. What sets this provider apart is how you connect it: the endpoint is
+per-location, the Google Cloud project is a separate setting, and the credential
+is a **service account key file**—not an API key.
+
+:::caution{title="Vertex AI doesn't accept API keys"}
+
+Every other AI Gateway provider takes an API key. Vertex doesn't: its prediction
+endpoints reject API keys outright, answering that they expect an OAuth2 access
+token instead. The provider dialog asks for the JSON key file of a Google Cloud
+service account, and the gateway exchanges it for short-lived access tokens on
+your behalf. Pasting an API key into the field fails validation before the
+provider is saved.
+
+:::
+
+## Model references include the publisher prefix
+
+Apps reference a provider's models as `providerName/model`. Every Vertex model
+ID is publisher-qualified, so a Vertex model reference has two slashes in it:
+
+```
+vertexai/google/gemini-3.7-flash
+└──┬───┘ └──────────┬──────────┘
+provider          model
+```
+
+Everything before the **first** slash is the provider name you chose, and
+everything after it is the model ID exactly as Vertex expects it. The publisher
+isn't always `google`—Model Garden models carry their own vendor's prefix. A
+provider named `vertexai` serves all of these:
+
+- `vertexai/google/gemini-3.7-flash`
+- `vertexai/qwen/qwen3-coder-480b-a35b-instruct-maas`
+- `vertexai/deepseek-ai/deepseek-v3.2-maas`
+- `vertexai/zai-org/glm-5-maas`
+
+Copy model IDs from the model picker rather than typing them—the `-maas` suffix
+and the publisher prefix are both part of the ID.
+
+## How the gateway calls Vertex AI
+
+When no valid cached token exists, the gateway uses the service account key to
+request a short-lived Google OAuth 2.0 access token. It caches and refreshes
+that token, then calls Vertex's OpenAI-compatible endpoint with the token as the
+bearer credential.
+
+<Diagram height="h-64">
+  <DiagramNode id="app">Your app</DiagramNode>
+  <DiagramNode id="gateway" variant="zuplo">
+    AI Gateway
+  </DiagramNode>
+  <DiagramNode id="oauth" variant="orange">
+    Google OAuth
+  </DiagramNode>
+  <DiagramGroup id="gcp" label="Your Google Cloud project">
+    <DiagramNode id="compat" variant="blue">
+      OpenAI-compatible endpoint
+    </DiagramNode>
+    <DiagramNode id="embed" variant="green">
+      Vertex embedding APIs
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramEdge from="app" to="gateway" label="Universal API" />
+  <DiagramEdge
+    from="gateway"
+    to="oauth"
+    label="service account key → access token"
+    lineStyle="dashed"
+  />
+  <DiagramEdge from="gateway" to="compat" label="chat completions" />
+  <DiagramEdge from="gateway" to="embed" label="embeddings" />
+</Diagram>
+
+The request URL the gateway builds combines both settings you enter:
+
+```
+https://us-central1-aiplatform.googleapis.com
+  /v1/projects/my-project-123/locations/us-central1/endpoints/openapi/chat/completions
+```
+
+The **location** lives in the hostname, which is why the provider dialog asks
+for a location instead of an endpoint URL. The **project** doesn't appear in the
+hostname at all—it appears only in the path—so it can't be derived from the
+endpoint and is a field of its own. That's why the project is required rather
+than optional: without it the gateway would have to guess, and a guess would
+send your traffic and your spend to someone else's Google Cloud project.
+
+## Supported endpoints
+
+| Endpoint               | Vertex AI models |
+| ---------------------- | ---------------- |
+| `/v1/chat/completions` | ✅ Forwarded     |
+| `/v1/embeddings`       | ✅ Translated    |
+| `/v1/responses`        | ❌               |
+| `/v1/messages`         | ❌               |
+
+Streaming (`stream: true`) works on chat completions.
+
+The gateway rejects `/v1/responses` and `/v1/messages` requests for Vertex
+models with a `400` error before any upstream call, because Vertex serves
+neither the OpenAI Responses API nor the Anthropic Messages API.
+
+:::note{title="Anthropic models on Vertex aren't supported"}
+
+Vertex also hosts Anthropic's Claude models, but on a different API surface than
+the one this provider uses. The gateway can't route to them. To use Claude
+models, add the [Anthropic](./providers.mdx) provider or
+[Bedrock Mantle](./bedrock-mantle.mdx).
+
+:::
+
+## Model availability depends on the location
+
+Google registers each Vertex model in specific locations, and it changes that
+list over time. Most Model Garden models are served only from the **global**
+location; the Gemini models are more widely available.
+
+The model picker doesn't filter by your provider's location, so every model
+stays selectable from every provider. If you call a model that isn't served
+where your provider points, Vertex answers with a `400` that names both:
+
+```
+Publisher model 'publishers/qwen/models/qwen3-coder-480b-a35b-instruct-maas'
+is not available in region 'us-central1'
+```
+
+Set the provider's **Location** to `global` if you plan to use Model Garden
+models, or add a second Vertex provider for a specific region and route to
+whichever one serves the model you want.
+
+## Before you begin
+
+You need:
+
+- A Google Cloud project with the **Vertex AI API**
+  (`aiplatform.googleapis.com`) enabled and billing enabled. Gemini models
+  require both.
+- A service account in that project holding the **Vertex AI User**
+  (`roles/aiplatform.user`) role, and a **JSON key** for it. The steps are in
+  [Set up Google Cloud](#set-up-google-cloud).
+- The project's **project ID**—the readable identifier such as `my-project-123`,
+  not the numeric project number.
+- An AI Gateway project in the Zuplo Portal.
+- An AI Gateway [app](./apps.mdx) to call the models from. The app page shows
+  the app's API URL, and its API key lives on the app's **API Key** tab.
+
+## Set up Google Cloud
+
+Do this before adding the provider—the key file you download in the last step is
+what the provider dialog asks for.
+
+<Stepper>
+
+1. In the [Google Cloud console](https://console.cloud.google.com/), select the
+   project you want to serve models from and note its **project ID**. The
+   console shows the ID next to the project name, alongside the project number;
+   the gateway needs the ID.
+
+1. Enable the **Vertex AI API** on the project, under **APIs & Services →
+   Library**. Confirm billing is enabled for the project as well.
+
+1. Create a service account under **IAM & Admin → Service Accounts**.
+
+1. Grant that service account the **Vertex AI User** (`roles/aiplatform.user`)
+   role **on the same project**. This is the smallest role that can call
+   prediction endpoints. Vertex AI Administrator grants more than the gateway
+   needs, and Vertex AI Viewer can't make predictions at all.
+
+1. Create a JSON key for the service account: open the service account, go to
+   **Keys → Add key → Create new key**, choose **JSON**, and download the file.
+   Keep it somewhere safe—Google doesn't let you download it again.
+
+</Stepper>
+
+:::note
+
+Enabling the API and granting the role are separate steps, and missing the first
+one is the most common setup failure. It surfaces as a `403` that talks about
+the Vertex AI API rather than about permissions, which reads like a bad key.
+
+:::
+
+## Add the provider
+
+Adding or editing providers requires the **Edit** permission, granted to Zuplo
+account and project **Admins**—see
+[Managing Providers](./managing-providers.mdx).
+
+<Stepper>
+
+1. Open
+   [**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models)
+   in your AI Gateway project in the Zuplo Portal.
+
+1. Click the **Add Provider** button.
+
+1. In the **AI Provider** list, select **Vertex AI** from the Default Providers
+   group.
+
+1. Review the **Provider Name**, which fills in as `vertexai` (a second
+   configuration becomes `vertexai-2`). You can replace it with your own name,
+   but only now—the name is permanent after creation, and it's the prefix in
+   every model reference: a provider named `vertexai` serves
+   `vertexai/google/gemini-3.7-flash`.
+
+1. In **Location**, enter the Vertex AI location to call, such as `us-central1`
+   or `europe-west4`. Enter `global` to use Vertex's global endpoint. The
+   gateway derives the endpoint from this value—there's no URL to enter.
+
+1. In **Google Cloud Project ID**, enter the project ID you noted earlier, such
+   as `my-project-123`. The dialog rejects an all-digits value, which is the
+   project number rather than the ID.
+
+1. In **Service Account Key (JSON)**, paste the entire contents of the JSON key
+   file you downloaded. Paste it whole—a truncated copy fails validation.
+
+1. Select the models to enable, or click **Select All**. The picker shows
+   Google's per-token prices, which the gateway uses to track cost per app. You
+   can change the selection later.
+
+1. Click **Create**.
+
+</Stepper>
+
+:::note
+
+Saving provider settings triggers an automatic production deployment of your
+gateway, because provider credentials are part of the deployed gateway. The
+change is live once the deployment completes.
+
+:::
+
+:::note{title="Prices in the picker are a snapshot"}
+
+The per-token prices shown in the model picker are recorded rates, not a live
+read of Google's price list, and some Gemini models are on promotional rates
+that Google marks as temporary. Treat the gateway's cost figures as an estimate
+and your Google Cloud bill as the record.
+
+:::
+
+When you edit the provider later—see
+[Managing Providers](./managing-providers.mdx)—the **Location** and **Google
+Cloud Project ID** fields show the saved values and stay editable, and you can
+replace the key file. Leave the key field blank to keep the stored key. The
+**Provider Name** doesn't change.
+
+## Verify the provider
+
+Once the deployment completes, send a chat completions request to your app's
+[Universal API](./universal-api.mdx) URL—shown at the top of the
+[app page](./apps.mdx)—with the app's API key as the bearer token and one of the
+models you enabled:
+
+```bash
+curl https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/chat/completions \
+  -H "Authorization: Bearer $ZUPLO_APP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "vertexai/google/gemini-3.7-flash",
+    "messages": [{ "role": "user", "content": "Say hi" }]
+  }'
+```
+
+The URL is a sample—replace it with your app's API URL plus
+`/v1/chat/completions`, set `ZUPLO_APP_API_KEY` to the app's API key, and
+substitute any model you enabled for `vertexai/google/gemini-3.7-flash`.
+
+A `200` response confirms the provider works; the body carries
+`"provider": "vertex-ai"`—the provider type, not the name you chose. If the
+request fails immediately after you save the provider, the deployment may not
+have finished—retry before debugging further.
+
+## Call the models
+
+Use any OpenAI client with your app's URL plus `/v1` as the base URL and the
+app's API key:
+
+```ts
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: process.env.ZUPLO_APP_API_KEY,
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
+});
+
+const response = await client.chat.completions.create({
+  model: "vertexai/google/gemini-3.7-flash",
+  messages: [{ role: "user", content: "Summarize this ticket." }],
+});
+```
+
+Streaming works the same way—set `stream: true` and read the
+`chat.completion.chunk` events.
+
+### Embeddings
+
+Embeddings use the same client and the same `/v1/embeddings` endpoint as any
+other provider:
+
+```ts
+const embeddings = await client.embeddings.create({
+  model: "vertexai/google/gemini-embedding-2",
+  input: ["first document", "second document"],
+});
+```
+
+`dimensions` and `encoding_format` both work. Two Vertex-specific limits apply,
+and the gateway enforces both before calling Vertex, so you get a `400` rather
+than a partial charge:
+
+- **At most 250 inputs per request.** Split larger batches yourself.
+- **Text input only.** Pre-tokenized input—arrays of token IDs, which the OpenAI
+  API also accepts—is rejected, because Vertex has no way to represent it. Send
+  the original text.
+
+## Troubleshooting
+
+**The dialog rejects your credential.** Vertex uses a service account, not an
+API key. The field takes the whole JSON key file downloaded from **IAM & Admin →
+Service Accounts → Keys**. The dialog also rejects a workload identity
+federation configuration—its `type` is `external_account` rather than
+`service_account`—and a file whose `private_key` isn't a PEM-encoded key. Paste
+the file exactly as downloaded, keeping the `\n` escapes intact.
+
+**The dialog rejects your project ID.** Project IDs are 6 to 30 characters:
+lowercase letters, digits, and hyphens, starting with a letter and not ending in
+one. An all-digits value is the project number, which the Google Cloud console
+shows next to the ID; the gateway needs the ID.
+
+**A request fails with a `403` about the Vertex AI API.** The API isn't enabled
+on the project. Enable **Vertex AI API** under **APIs & Services → Library** and
+confirm the project has billing enabled. This error names the API rather than
+permissions, so it's easy to mistake for a credential problem.
+
+**A request fails with a permission error.** The service account is missing the
+**Vertex AI User** (`roles/aiplatform.user`) role, or holds it on a different
+project than the one configured on the provider. Grant the role on the same
+project you entered as the **Google Cloud Project ID**.
+
+**A request fails with `400` saying the model isn't available in the region.**
+The model isn't served from your provider's location. Most Model Garden models
+are global-only—see
+[Model availability](#model-availability-depends-on-the-location). Set the
+provider's **Location** to `global`, or use a provider that points at a location
+serving that model.
+
+**An embeddings request fails with `400` about the input.** The gateway accepts
+at most 250 inputs per request and text input only. See
+[Embeddings](#embeddings).
+
+**A `/v1/responses` or `/v1/messages` request fails with `400`.** Vertex's
+OpenAI-compatible endpoint serves neither API. Use `/v1/chat/completions`, or
+another provider for those endpoints—see
+[Supported endpoints](#supported-endpoints).
+
+## Next steps
+
+- [AI Providers](./providers.mdx)—the capability matrix across every supported
+  provider.
+- [Universal API](./universal-api.mdx)—the endpoints every app serves and how
+  model references work.
+- [Managing Providers](./managing-providers.mdx)—edit models, keys, the
+  location, and the project, and understand when changes deploy.
+- [AI Gateway Apps](./apps.mdx)—create the apps that call your Vertex-backed
+  models.
+- [Model Filtering policy](../policies/ai-gateway-model-filtering-v2-inbound.mdx)—control
+  which models each app can call.

package/docs/api-management/{introduction.md → overview.md}

@@ -1,6 +1,9 @@
 ---
-title: Zuplo API Management
-sidebar_label: Introduction
+title: API Management overview
+sidebar_label: Overview
+description:
+  Secure, transform, and operate APIs with Zuplo's programmable gateway,
+  built-in policies, analytics, and developer tooling.
 ---
 
 The Zuplo Gateway is a fully-managed, lightweight API management platform
@@ -11,8 +14,8 @@ engineering team, Zuplo makes it easy to:
 - [Add authentication and access control](../articles/step-3-add-api-key-auth.mdx)
 - [Implement rate limiting](../articles/step-2-add-rate-limiting.mdx)
 - Write custom logic to run at the gateway layer
-- Build a [rich developer portal](../dev-portal/introduction.mdx) with
-  self-serve tools for auth and monetization
+- Build a [rich developer portal](../dev-portal/overview.mdx) with self-serve
+  tools for auth and monetization
 
 Zuplo delivers the core benefits of API management without the overhead of
 legacy platforms. That means no expensive licensing, training requirements, or

package/docs/articles/api-key-administration.mdx

@@ -28,12 +28,11 @@ Once a consumer is created, view or copy its API Key using the icons shown.
 
 ![A consumer row with icons to view and copy its API key](../../public/media/api-key-administration/image-5.png)
 
-If you're using the Zuplo [Developer Portal](../dev-portal/introduction.mdx),
-we've an integration with the API Key API that allows developers to access their
-API keys, create new ones and delete them. To enable this, you must assign one
-or more managers, via e-mail, to be a manager for your API Key Consumer. This is
-optional if you aren't using the
-[Developer Portal](../dev-portal/introduction.mdx).
+If you're using the Zuplo [Developer Portal](../dev-portal/overview.mdx), we've
+an integration with the API Key API that allows developers to access their API
+keys, create new ones and delete them. To enable this, you must assign one or
+more managers, via e-mail, to be a manager for your API Key Consumer. This is
+optional if you aren't using the [Developer Portal](../dev-portal/overview.mdx).
 
 You can assign managers from your project's
 [Services](https://portal.zuplo.com/+/account/project/services) page in the

package/docs/articles/api-key-consumer-bucket-portal-ui.mdx

@@ -101,11 +101,11 @@ the API Key Authentication policy's `bucketId` option takes.
 
 ### Consumer form fields
 
-| Field            | Required | Runtime value       | Notes                                                                                                                           |
-| ---------------- | -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| **Subject**      | Yes      | `request.user.sub`  | Unique within the bucket. Identifies the consumer in logs and policy code.                                                      |
-| **Key managers** | No       | n/a                 | Comma-separated emails of users who can manage this consumer's keys via the [Developer Portal](../dev-portal/introduction.mdx). |
-| **Metadata**     | No       | `request.user.data` | Valid JSON object. Plan info, customer IDs, anything your policies need at runtime.                                             |
+| Field            | Required | Runtime value       | Notes                                                                                                                       |
+| ---------------- | -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **Subject**      | Yes      | `request.user.sub`  | Unique within the bucket. Identifies the consumer in logs and policy code.                                                  |
+| **Key managers** | No       | n/a                 | Comma-separated emails of users who can manage this consumer's keys via the [Developer Portal](../dev-portal/overview.mdx). |
+| **Metadata**     | No       | `request.user.data` | Valid JSON object. Plan info, customer IDs, anything your policies need at runtime.                                         |
 
 :::tip
 

package/docs/articles/api-key-end-users.mdx

@@ -52,9 +52,9 @@ keys or create new keys for your consumers manually.
 
 ## Zuplo Developer Portal
 
-If you publish a [Zuplo Developer Portal](../dev-portal/introduction.mdx) for
-your API consumers, you can let authenticated users manage their own keys
-without contacting your team.
+If you publish a [Zuplo Developer Portal](../dev-portal/overview.mdx) for your
+API consumers, you can let authenticated users manage their own keys without
+contacting your team.
 
 By default, a consumer's keys are visible to any signed-in user whose email
 matches a manager email assigned to that consumer. Consumers can copy and rotate

package/docs/articles/custom-domains.mdx

@@ -20,7 +20,7 @@ Zuplo supports two types of custom domains that can be configured separately:
 2. **Developer Portal Custom Domain**: For your developer documentation site
    (for example, `docs.example.com`). This domain uses the CNAME
    `cname.zuplodocs.com`. Learn more about the Developer Portal in the
-   [Developer Portal documentation](/docs/dev-portal/introduction).
+   [Developer Portal documentation](/docs/dev-portal/overview).
 
 Both types of custom domains can be managed from the same Custom Domains section
 in your project settings and follow a similar configuration process.

package/docs/articles/environment-variables.mdx

@@ -72,7 +72,7 @@ Environment variables can't start with `ZUPLO_` or `__ZUPLO`. The same
 restriction applies to names beginning with `ZUDOKU_`.
 
 If you need a variable that's exposed to the
-[Developer Portal](../dev-portal/introduction.mdx) build, prefix it with
+[Developer Portal](../dev-portal/overview.mdx) build, prefix it with
 `ZUPLO_PUBLIC_` (or `ZUDOKU_PUBLIC_`). Public-prefixed variables are bundled
 into the portal's static output and **must not contain secrets**, as they're
 visible to anyone who loads the page.

package/docs/articles/feature-flags.mdx

@@ -398,10 +398,10 @@ reads with the patterns above.
 ## Gate an MCP server with flags
 
 If you're fronting an MCP server with the
-[MCP Gateway](../mcp-gateway/introduction.mdx), the same policies apply — MCP
-routes run the standard inbound policy chain before the handler. Add your
-feature-gate policy to the MCP route to control access per user or plan, for
-example to make MCP access a paid-tier feature or to turn off a beta server.
+[MCP Gateway](../mcp-gateway/overview.mdx), the same policies apply — MCP routes
+run the standard inbound policy chain before the handler. Add your feature-gate
+policy to the MCP route to control access per user or plan, for example to make
+MCP access a paid-tier feature or to turn off a beta server.
 
 For curating _which tools_ a server exposes, start with the static
 [capability filtering](../mcp-gateway/capability-filtering.mdx) policy, which

package/docs/articles/migrate-from-apigee.md

@@ -84,7 +84,7 @@ Zuplo has a video walkthrough of the Apigee to Zuplo migration process:
 | Environment             | [Environment](./environments.md)                                       |
 | API Product             | API key with [metadata](./api-key-management.md)                       |
 | Developer App           | [API key consumer](./api-key-management.md)                            |
-| Apigee Developer Portal | [Zuplo Developer Portal](../dev-portal/introduction.md)                |
+| Apigee Developer Portal | [Zuplo Developer Portal](../dev-portal/overview.mdx)                   |
 | VerifyAPIKey policy     | [API Key Authentication](../policies/api-key-inbound.md)               |
 | OAuthV2 policy          | [JWT authentication policies](../policies/open-id-jwt-auth-inbound.md) |
 | SpikeArrest             | [Rate Limiting](../policies/rate-limit-inbound.md)                     |
@@ -306,7 +306,7 @@ export default async function (
 ### Step 5: Migrate your developer portal
 
 Apigee's Drupal-based developer portal requires significant setup and
-maintenance. Zuplo's [Developer Portal](../dev-portal/introduction.md) is
+maintenance. Zuplo's [Developer Portal](../dev-portal/overview.mdx) is
 automatically generated from your OpenAPI spec and includes:
 
 - Interactive API reference documentation
@@ -404,5 +404,5 @@ between both gateways.
 - [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
 - [Add rate limiting](./step-2-add-rate-limiting.md)
 - [Add API key authentication](./step-3-add-api-key-auth.md)
-- [Configure your developer portal](../dev-portal/introduction.md)
+- [Configure your developer portal](../dev-portal/overview.mdx)
 - [Set up source control](./source-control.md)

package/docs/articles/migrate-from-aws-api-gateway.md

@@ -244,5 +244,5 @@ secrets to secure the connection between Zuplo and your AWS backends.
 - [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
 - [Add rate limiting](./step-2-add-rate-limiting.md)
 - [Add API key authentication](./step-3-add-api-key-auth.md)
-- [Configure your developer portal](../dev-portal/introduction.md)
+- [Configure your developer portal](../dev-portal/overview.mdx)
 - [Set up source control](./source-control.md)