zuplo 6.71.10 → 6.71.12

package/docs/articles/monetization/monetization-policy.md

@@ -61,13 +61,14 @@ reads the API key from the `Authorization` header, validates it, and sets
 
 ## Configuration options
 
-| Option               | Type               | Default           | Description                                       |
-| -------------------- | ------------------ | ----------------- | ------------------------------------------------- |
-| `meters`             | object             | _(none)_          | Map of meter keys to increment values             |
-| `meterOnStatusCodes` | string or number[] | `"200-299"`       | Status code range to meter                        |
-| `authHeader`         | string             | `"authorization"` | Header to read the API key from                   |
-| `authScheme`         | string             | `"Bearer"`        | Expected auth scheme prefix                       |
-| `cacheTtlSeconds`    | number             | `60`              | How long to cache subscription data (minimum 60s) |
+| Option                 | Type               | Default           | Description                                           |
+| ---------------------- | ------------------ | ----------------- | ----------------------------------------------------- |
+| `meters`               | object             | _(none)_          | Map of meter keys to increment values                 |
+| `requiredEntitlements` | string[]           | _(none)_          | Entitlement keys the subscription must have access to |
+| `meterOnStatusCodes`   | string or number[] | `"200-299"`       | Status code range to meter                            |
+| `authHeader`           | string             | `"authorization"` | Header to read the API key from                       |
+| `authScheme`           | string             | `"Bearer"`        | Expected auth scheme prefix                           |
+| `cacheTtlSeconds`      | number             | `60`              | How long to cache subscription data (minimum 60s)     |
 
 ### `meters`
 
@@ -91,6 +92,23 @@ see the [Dynamic Metering](./dynamic-metering.md) guide.
 { "meters": { "api_credits": 10 } }
 ```
 
+### `requiredEntitlements`
+
+A list of [entitlement](./features.mdx) keys the caller's subscription must have
+access to before the request is allowed. Use it to gate a route on a feature —
+for example, restrict it to plans that include `custom_domains` — without
+writing code.
+
+```json
+{ "requiredEntitlements": ["custom_domains"] }
+```
+
+The request is allowed only when **every** listed entitlement is present with
+`hasAccess` set to `true`. If any is missing, disabled, or has exhausted its
+quota, the policy returns `403 Forbidden` before the request reaches your
+backend. For access checks that need runtime logic, gate in code instead — see
+[Programmatic Monetization](./programmatic-monetization.md).
+
 ### `meterOnStatusCodes`
 
 Controls which responses count toward metering. By default, only successful
@@ -256,22 +274,23 @@ the RFC 7807 Problem Details format:
 
 Common error details:
 
-| Condition                        | `detail` message                                                    |
-| -------------------------------- | ------------------------------------------------------------------- |
-| No auth header                   | `"No Authorization Header"`                                         |
-| Wrong auth scheme                | `"Invalid Authorization Scheme"`                                    |
-| Empty key after the auth scheme  | `"No key present"`                                                  |
-| Cached invalid key or 401        | `"Authorization Failed"`                                            |
-| Invalid API key                  | `"API Key is invalid or does not have access to the API"`           |
-| Expired API key                  | `"API Key has expired."`                                            |
-| Expired subscription             | `"API Key has an expired subscription."`                            |
-| Subscription has no payment      | `"Subscription payment status is not available."`                   |
-| Payment not made                 | `"Payment has not been made."`                                      |
-| Payment overdue                  | `"Payment is overdue. Please update your payment method."`          |
-| Subscription has no entitlements | `"Subscription entitlements are not available."`                    |
-| Meter not in subscription        | `"API Key does not have \"X\" meter provided by the subscription."` |
-| Quota exhausted                  | `"API Key has exceeded the allowed limit for \"X\" meter."`         |
-| Meter access denied              | `"API Key does not have access to \"X\" meter."`                    |
+| Condition                        | `detail` message                                                                   |
+| -------------------------------- | ---------------------------------------------------------------------------------- |
+| No auth header                   | `"No Authorization Header"`                                                        |
+| Wrong auth scheme                | `"Invalid Authorization Scheme"`                                                   |
+| Empty key after the auth scheme  | `"No key present"`                                                                 |
+| Cached invalid key or 401        | `"Authorization Failed"`                                                           |
+| Invalid API key                  | `"API Key is invalid or does not have access to the API"`                          |
+| Expired API key                  | `"API Key has expired."`                                                           |
+| Expired subscription             | `"API Key has an expired subscription."`                                           |
+| Subscription has no payment      | `"Subscription payment status is not available."`                                  |
+| Payment not made                 | `"Payment has not been made."`                                                     |
+| Payment overdue                  | `"Payment is overdue. Please update your payment method."`                         |
+| Subscription has no entitlements | `"Subscription entitlements are not available."`                                   |
+| Meter not in subscription        | `"API Key does not have \"X\" meter provided by the subscription."`                |
+| Quota exhausted                  | `"API Key has exceeded the allowed limit for \"X\" meter."`                        |
+| Meter access denied              | `"API Key does not have access to \"X\" meter."`                                   |
+| Required entitlement missing     | `"The required \"X\" entitlement is not allowed or its quota has been exhausted."` |
 
 ## Pipeline ordering
 

package/docs/articles/monetization/programmatic-monetization.md

@@ -74,6 +74,35 @@ if (!advancedSearch?.hasAccess) {
 }
 ```
 
+:::tip
+
+If you only need to check that a feature's entitlement has access — with no
+other runtime logic — skip the custom code and use the policy's
+[`requiredEntitlements`](./monetization-policy.md#requiredentitlements) option
+instead. It rejects the request with `403 Forbidden` when any listed entitlement
+is missing or out of quota:
+
+```json
+// config/policies.json
+{
+  "name": "monetization-inbound",
+  "policyType": "monetization-inbound",
+  "handler": {
+    "export": "MonetizationInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "meters": { "api_requests": 1 },
+      "requiredEntitlements": ["advanced_search"]
+    }
+  }
+}
+```
+
+Reach for the code path below when the decision needs more than a presence check
+— inspecting the plan key, reading the request, or combining conditions.
+
+:::
+
 Register the policy and apply it after `monetization-inbound` on the routes you
 want to protect:
 

package/docs/articles/securing-the-gateway-with-client-mtls.mdx

@@ -88,12 +88,26 @@ zuplo ca-certificate list --account your-account
 See the [`ca-certificate` CLI reference](../cli/ca-certificate-create.mdx) for
 all available subcommands (`create`, `list`, `describe`, `update`, `delete`).
 
-:::tip{title="Using an intermediate CA"}
+:::caution{title="Upload the self-signed root CA, not an intermediate"}
 
-If your client certificates are issued by an intermediate CA (rather than
-directly by your root), upload the root CA certificate that anchors the chain.
-Clients must send the leaf certificate plus any intermediate certificates when
-they connect.
+Zuplo must build a complete chain from the presented client certificate up to a
+trust anchor. Upload the **self-signed root** CA that anchors the chain — not an
+intermediate or subordinate CA. Uploading a subordinate CA is the most common
+cause of the `FAILED to get issuer certificate` error (see
+[Troubleshooting](#failed-to-get-issuer-certificate)).
+
+To confirm a certificate is a self-signed root, check that its subject and
+issuer are identical:
+
+```bash
+openssl x509 -in ca.pem -noout -subject -issuer -nameopt RFC2253
+```
+
+If `subject` and `issuer` match, it's a root. If they differ, the file is an
+intermediate CA — trace the chain to the root and upload that instead. When your
+client certificates are issued by an intermediate CA, clients still send the
+leaf certificate plus any intermediates when they connect (see
+[Test with curl](#4-test-with-curl)).
 
 :::
 
@@ -315,11 +329,73 @@ the policy in a working-copy or preview environment.
   `context.incomingRequestProperties.clientMtlsVerificationReason` to see why
   verification failed.
 
+### `FAILED to get issuer certificate`
+
+This error means Zuplo can't build a complete chain from the presented client
+certificate up to a trusted root. The usual cause is uploading an **intermediate
+or subordinate CA** instead of the **self-signed root** CA that anchors the
+chain.
+
+Confirm what you uploaded. A self-signed root has an identical subject and
+issuer:
+
+```bash
+openssl x509 -in ca.pem -noout -subject -issuer -nameopt RFC2253
+```
+
+If `subject` and `issuer` differ, the file is an intermediate CA. Find the root
+that anchors the chain and re-upload it:
+
+```bash
+# Remove the incorrect CA
+zuplo ca-certificate delete --cert-id mtlsca_abc123 --account your-account
+
+# Upload the self-signed root instead
+zuplo ca-certificate create --name my_ca --cert ./root-ca.pem --account your-account
+```
+
+If your CA is an Active Directory Certificate Services (AD CS) deployment,
+export the issuing CA's own certificate and inspect it:
+
+```bash
+# Export the CA certificate (often DER-encoded)
+certutil -ca.cert ca.cer
+
+# Convert DER to the PEM format Zuplo requires
+openssl x509 -inform der -in ca.cer -out ca.pem
+
+# Verify subject == issuer (a root); if not, export the root above it instead
+openssl x509 -in ca.pem -noout -subject -issuer -nameopt RFC2253
+```
+
+### `client certificate metadata not provided`
+
+The certificate verified at the edge, but the parsed certificate wasn't
+forwarded to your gateway workers, so `request.user.data.mtlsAuth` is empty even
+though the request was authenticated.
+
+The most common cause is an **oversized leaf client certificate**. Zuplo's edge
+can only forward client certificates up to roughly 10 KB of DER-encoded data.
+Certificates with large RSA keys, many Subject Alternative Names, or large
+custom extensions can exceed this. Check the DER size of the leaf certificate:
+
+```bash
+openssl x509 -in client.pem -outform der | wc -c
+```
+
+If the result is near or above ~10,000 bytes, reissue a smaller leaf
+certificate. Trim unnecessary extensions and SANs, or switch to ECDSA keys
+instead of large (4096-bit) RSA keys. This limit applies to the **leaf**
+certificate the edge forwards, not the full chain.
+
 ### `request.user.data.mtlsAuth` is missing
 
 - The policy only attaches metadata when a parseable client certificate is
   present on the request. Confirm the client is sending one.
 - Verify the route includes the `mtls-auth-inbound` policy.
+- If the certificate verifies but metadata is still missing, check the leaf
+  certificate size (see
+  [`client certificate metadata not provided`](#client-certificate-metadata-not-provided)).
 
 ### Custom domains
 
@@ -331,6 +407,27 @@ that custom domain.
 If you add a custom domain later and your clients aren't being verified against
 it, contact [support@zuplo.com](mailto:support@zuplo.com).
 
+### Custom domains behind your own CDN
+
+Inbound mTLS requires the TLS handshake to terminate at Zuplo's edge, because
+that's where the client certificate is verified and parsed. If you front your
+Zuplo gateway with **your own CDN** (for example, your own Cloudflare zone) that
+terminates TLS before traffic reaches Zuplo, the handshake — and the client
+certificate — ends at your CDN. Zuplo never sees the certificate, so the
+`mtls-auth-inbound` policy has nothing to verify.
+
+You have two supported options:
+
+- **Let Zuplo terminate TLS.** Point clients at a Zuplo-managed gateway domain,
+  or configure your custom domain directly on Zuplo so Zuplo terminates TLS. The
+  client certificate then reaches Zuplo's edge and inbound mTLS works as
+  documented above.
+- **Verify mTLS at your CDN.** If you must keep your own CDN in front, terminate
+  and verify the client certificate at the CDN, then forward the verified
+  identity to Zuplo in a request header. Validate that header in a Zuplo policy
+  instead of relying on `mtls-auth-inbound`. Make sure the header can't be
+  spoofed by clients that bypass your CDN.
+
 ## Additional resources
 
 - [`mtls-auth-inbound` policy reference](../policies/mtls-auth-inbound.mdx)

package/docs/dev-portal/zudoku/configuration/navigation.mdx

@@ -143,7 +143,10 @@ type NavigationCategory = {
   collapsible?: boolean;
   collapsed?: boolean;
   stack?: boolean; // open the category's items as a stacked sub-nav
-  link?: string | { type: "doc"; file: string; label?: string; path?: string };
+  link?:
+    | string
+    | { type: "doc"; file: string; label?: string; path?: string }
+    | { type: "link"; to: string; label?: string };
   display?:
     | "auth"
     | "anon"
@@ -158,9 +161,11 @@ type NavigationCategory = {
 #### Category links
 
 A category can have a `link` property that makes the category label itself clickable, navigating to
-a document. This is useful when you want a category that acts as both a group and a landing page.
+a document, a path, or an external URL. This is useful when you want a category that acts as both a
+group and a landing page.
 
-The `link` can be a simple string pointing to a file path, or an object for more control:
+The `link` can be a simple string pointing to a file path, a `doc` object for more control, or a
+`link` object that points the category label at an arbitrary path or external URL:
 
 ```tsx title="String shorthand"
 {
@@ -190,7 +195,7 @@ The `link` can be a simple string pointing to a file path, or an object for more
 }
 ```
 
-The object form supports these properties:
+The `doc` object form supports these properties:
 
 | Property | Type     | Description                                              |
 | -------- | -------- | -------------------------------------------------------- |
@@ -199,6 +204,29 @@ The object form supports these properties:
 | `label`  | `string` | Override the label (defaults to the document title)      |
 | `path`   | `string` | Custom URL path (overrides the default file-based route) |
 
+```tsx title="Link form pointing to a path or external URL"
+{
+  type: "category",
+  label: "API Reference",
+  link: {
+    type: "link",
+    to: "/api",
+  },
+  items: [
+    "guides/authentication",
+    "guides/rate-limits",
+  ],
+}
+```
+
+The `link` object form supports these properties:
+
+| Property | Type     | Description                         |
+| -------- | -------- | ----------------------------------- |
+| `type`   | `"link"` | Must be `"link"`                    |
+| `to`     | `string` | Path or external URL to navigate to |
+| `label`  | `string` | Override the category label         |
+
 ### `type: doc`
 
 Doc is used to reference markdown files. The `label` is the text that will be displayed, and the

package/docs/guides/transform-route-params-url-rewrite.mdx

@@ -0,0 +1,307 @@
+---
+title: Transform Route Parameters for URL Rewrite
+sidebar_label: Transform Route Parameters
+description:
+  Learn how to use an inbound policy to transform route parameter values before
+  the URL Rewrite handler forwards the request to your backend.
+tags:
+  - custom-code
+  - backends
+---
+
+This guide explains how to transform incoming route parameter values in an
+inbound policy before the [URL Rewrite handler](../handlers/url-rewrite.mdx)
+uses them to build the upstream URL. This pattern is useful when your public API
+paths use different naming conventions than your internal backend.
+
+## Overview
+
+When you use the URL Rewrite handler, it builds the upstream URL by
+interpolating values like `${params.resourceType}` directly from the incoming
+route parameters. Sometimes, however, you need to **change** those values before
+the rewrite happens. Common scenarios include:
+
+- **Value mapping** — translating a public-facing parameter like `order` to an
+  internal value like `customerorder`
+- **Case normalization** — converting `Products` to `products` before forwarding
+- **Path translation** — mapping user-friendly slugs to internal identifiers
+
+The recommended approach is to read the route parameters in an inbound policy,
+transform them, store the results on
+[`context.custom`](../programmable-api/zuplo-context.mdx), and reference the
+transformed values in the URL Rewrite pattern.
+
+## Step-by-Step Example
+
+The solution has three parts: an **inbound policy** that reads `request.params`
+and stores transformed values on `context.custom`, a **URL Rewrite handler**
+that references those values using `${context.custom.*}` in the
+`rewritePattern`, and **route configuration** that wires the two together.
+
+Imagine your public API exposes a route like `/api/:resourceType/:resourceId`,
+but your backend expects the resource type to be prefixed with `customer`. A
+request to `/api/order/123` should be forwarded to
+`https://backend.example.com/api/customerorder/123`.
+
+### 1. Write the Inbound Policy
+
+Create a custom inbound policy that reads the route parameters, transforms the
+values, and stores them on `context.custom`:
+
+```ts title="modules/transform-params.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  // Read the original route parameter
+  const resourceType = request.params.resourceType;
+
+  // Transform the value — prefix with "customer"
+  const transformedResourceType = `customer${resourceType}`;
+
+  // Store the transformed value on context.custom
+  context.custom.transformedResourceType = transformedResourceType;
+
+  context.log.info({
+    message: "Transformed route parameter",
+    original: resourceType,
+    transformed: transformedResourceType,
+  });
+
+  return request;
+}
+```
+
+### 2. Register the Policy
+
+Add the policy to `config/policies.json`:
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "transform-params",
+      "policyType": "custom-code-inbound",
+      "handler": {
+        "export": "default",
+        "module": "$import(./modules/transform-params)"
+      }
+    }
+  ]
+}
+```
+
+### 3. Configure the Route
+
+Define the route in `config/routes.oas.json` with the inbound policy and a URL
+Rewrite handler that references `context.custom`:
+
+```json title="config/routes.oas.json"
+{
+  "paths": {
+    "/api/{resourceType}/{resourceId}": {
+      "x-zuplo-path": {
+        "pathMode": "open-api"
+      },
+      "get": {
+        "summary": "Get resource by type and ID",
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "export": "urlRewriteHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "rewritePattern": "https://backend.example.com/api/${context.custom.transformedResourceType}/${params.resourceId}"
+            }
+          },
+          "policies": {
+            "inbound": ["transform-params"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+With this configuration, a request to `/api/order/123` flows through the
+pipeline as follows:
+
+1. The route matches with `params.resourceType = "order"` and
+   `params.resourceId = "123"`
+2. The `transform-params` inbound policy runs and sets
+   `context.custom.transformedResourceType = "customerorder"`
+3. The URL Rewrite handler builds the upstream URL:
+   `https://backend.example.com/api/customerorder/123`
+
+## Common Pitfall: Modifying `request.params` Directly
+
+:::caution
+
+Do not try to transform route parameters by constructing a new `ZuploRequest`
+with modified `params` and expecting the URL Rewrite handler to pick them up.
+
+:::
+
+A common first attempt is to create a new
+[`ZuploRequest`](../programmable-api/zuplo-request.mdx) with different `params`:
+
+```ts
+// ⚠️ This approach does NOT work as expected with URL Rewrite
+const newRequest = new ZuploRequest(request, {
+  params: {
+    ...request.params,
+    resourceType: "customerorder",
+  },
+});
+return newRequest;
+```
+
+In practice, the URL Rewrite handler evaluates `${params.*}` against the
+route-level parameters rather than the request object returned by a policy. This
+means the rewritten URL may contain `undefined` segments instead of your
+transformed values. Use `context.custom` for reliable interpolation of
+transformed values — the URL Rewrite handler's `rewritePattern` fully supports
+`${context.custom.*}`, and values set in an inbound policy are available when
+the handler runs.
+
+## Variations
+
+### Using a Lookup Map
+
+For more complex mappings where the transformation is not a simple string
+operation, use a lookup object:
+
+```ts title="modules/transform-params-map.ts"
+import { ZuploContext, ZuploRequest, HttpProblems } from "@zuplo/runtime";
+
+// Map public resource types to internal names
+const RESOURCE_TYPE_MAP: Record<string, string> = {
+  order: "customerorder",
+  invoice: "billing-invoice",
+  profile: "user-profile",
+  subscription: "recurring-plan",
+};
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  const resourceType = request.params.resourceType;
+  const mappedType = RESOURCE_TYPE_MAP[resourceType];
+
+  if (!mappedType) {
+    return HttpProblems.notFound(request, context, {
+      detail: `Unknown resource type: ${resourceType}`,
+    });
+  }
+
+  context.custom.transformedResourceType = mappedType;
+
+  return request;
+}
+```
+
+### Transforming Multiple Parameters
+
+You can transform any number of route parameters and store each on
+`context.custom`. Reference them individually in the rewrite pattern:
+
+```ts title="modules/transform-multiple-params.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  // Normalize casing
+  context.custom.version = request.params.version?.toLowerCase();
+
+  // Map resource type
+  context.custom.resource =
+    request.params.resource === "users" ? "customers" : request.params.resource;
+
+  return request;
+}
+```
+
+Then use both values in the rewrite pattern:
+
+```json
+{
+  "rewritePattern": "https://backend.example.com/${context.custom.version}/${context.custom.resource}/${params.id}"
+}
+```
+
+### Combining with Body Transformation
+
+If your API also needs to transform values in the request body alongside route
+parameters, you can handle both in the same inbound policy. Create a new
+`ZuploRequest` with a modified body while storing the route parameter
+transformations on `context.custom`:
+
+```ts title="modules/transform-params-and-body.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  // Transform route parameter
+  context.custom.transformedResourceType = `customer${request.params.resourceType}`;
+
+  // Transform the request body if present
+  if (request.headers.get("content-type")?.includes("application/json")) {
+    const body = await request.json();
+
+    // Map fields in the body to match the backend schema
+    const transformedBody = {
+      ...body,
+      type: context.custom.transformedResourceType,
+    };
+
+    // Return a new request with the modified body
+    return new ZuploRequest(request, {
+      body: JSON.stringify(transformedBody),
+    });
+  }
+
+  return request;
+}
+```
+
+## Best Practices
+
+- **Use descriptive keys on `context.custom`** — names like
+  `context.custom.transformedResourceType` are easier to debug than generic keys
+  like `context.custom.value`
+- **Log transformations** — use `context.log` to record original and transformed
+  values so you can trace issues in production
+- **Validate before transforming** — return an appropriate error response (using
+  [`HttpProblems`](../programmable-api/http-problems.mdx)) if a parameter value
+  is unexpected, rather than forwarding bad data to your backend
+- **Keep the policy focused** — if your transformation logic is complex,
+  consider splitting it into a separate utility module imported by the policy
+
+## Next Steps
+
+- [URL Rewrite Handler](../handlers/url-rewrite.mdx) — full reference for
+  rewrite patterns and available interpolation variables
+- [Custom Code Patterns](../articles/custom-code-patterns.md) — common patterns
+  for writing inbound policies, outbound policies, and handlers
+- [ZuploContext](../programmable-api/zuplo-context.mdx) — reference for
+  `context.custom` and other context properties
+- [ZuploRequest](../programmable-api/zuplo-request.mdx) — reference for
+  `request.params` and constructing new requests
+- [User-Based Backend Routing](./user-based-backend-routing.mdx) — a related
+  pattern using `context.custom` with URL Rewrite for routing by user identity

package/docs/mcp-gateway/cross-app-access/overview.mdx

@@ -0,0 +1,204 @@
+---
+title: "Cross App Access (XAA)"
+sidebar_label: "Overview"
+description: |
+  What Cross App Access (XAA) and the Identity Assertion JWT Authorization Grant
+  (ID-JAG) are, the problem they solve for AI agents and MCP, and how the Zuplo
+  MCP Gateway performs the token exchange so your MCP servers and clients don't
+  have to.
+---
+
+:::note{title="Beta"}
+
+Cross App Access support is in beta and builds on the
+[MCP Gateway](../introduction.mdx), which is also in beta. The configuration
+model and policy options may change before general availability.
+
+:::
+
+Cross App Access (XAA) lets one application reach another application's API on a
+user's behalf **through the identity provider both apps already trust** —
+instead of running a separate, point-to-point OAuth connection between them. For
+AI agents and MCP, that means an agent can call a protected upstream MCP server
+for a user without the user re-consenting to every app pair, and without
+credentials sprawling outside the identity provider's view.
+
+The Zuplo MCP Gateway sits in the middle of this flow and runs the XAA token
+exchange for you. An MCP client connects to the gateway with ordinary MCP OAuth;
+the gateway, acting as the XAA _requesting app_, mints the cross-app grant from
+your identity provider and redeems it at the upstream's authorization server.
+Neither the MCP client nor the upstream MCP server has to implement XAA itself.
+
+## The problem XAA solves
+
+Single sign-on (SSO) solves _login_: a user authenticates once with an identity
+provider (Okta, Microsoft Entra, Auth0) and gets into every connected app. SSO
+does **not** solve _app-to-app API access_. When one app needs to call another
+app's API on the user's behalf, the two apps today run a direct OAuth flow
+between themselves. The
+[IETF draft](https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/)
+describes this as a connection that "bypasses the trusted identity provider" and
+is "invisible to the identity provider managing the ecosystem."
+
+AI agents make this gap urgent. An agent in one app increasingly needs to reach
+into other SaaS apps' data on the user's behalf. The naive approach produces:
+
+- **Consent-screen sprawl** — the user re-authorizes every agent against every
+  downstream app individually.
+- **Credential sprawl** — long-lived tokens scattered per app pair, invisible to
+  IT.
+- **No central governance** — security teams can't see or control what connects
+  to what, and offboarding means hunting access down service by service.
+
+XAA routes app-to-app access back through the identity provider both apps
+already trust. The IdP becomes the single place where IT decides which app can
+talk to which app, enforces conditional-access policy, and audits every
+delegation — while the upstream app's authorization server stays the
+access-token issuer. The trust boundary isn't broken; it's brokered.
+
+## How the flow works
+
+XAA is defined by the **Identity Assertion JWT Authorization Grant (ID-JAG)** —
+`draft-ietf-oauth-identity-assertion-authz-grant`. It chains two OAuth exchanges
+across two authorization servers:
+
+1. **Identity assertion → ID-JAG**, at the identity provider, using
+   [RFC 8693 token exchange](https://www.rfc-editor.org/rfc/rfc8693). The
+   requesting app presents the user's ID token (the identity assertion) and asks
+   for a grant scoped to one specific target authorization server. The IdP
+   evaluates policy and returns a short-lived, audience-restricted **ID-JAG** —
+   a signed JWT with the header `typ: oauth-id-jag+jwt`.
+2. **ID-JAG → access token**, at the upstream's resource authorization server,
+   using the
+   [RFC 7523 JWT bearer grant](https://www.rfc-editor.org/rfc/rfc7523). The
+   requesting app presents the ID-JAG as an `assertion` and receives a normal
+   access token for the upstream API.
+
+The ID-JAG is a _grant_, not an access token — it can't call an API directly. It
+exists only to be redeemed in the second exchange.
+
+When the Zuplo gateway fronts an XAA-protected upstream, the gateway plays the
+**requesting app** for both exchanges:
+
+<Diagram height="h-80">
+  <DiagramNode id="client">MCP Client</DiagramNode>
+  <DiagramGroup id="gateway" label="Zuplo MCP Gateway (requesting app)">
+    <DiagramNode id="inbound" variant="zuplo">
+      OAuth 2.1 server
+    </DiagramNode>
+    <DiagramNode id="requestor" variant="zuplo">
+      XAA requestor
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramNode id="idp">Identity Provider</DiagramNode>
+  <DiagramGroup id="upstream" label="Upstream app">
+    <DiagramNode id="ras">Resource AS</DiagramNode>
+    <DiagramNode id="mcp">MCP server</DiagramNode>
+  </DiagramGroup>
+  <DiagramEdge from="client" to="inbound" label="MCP OAuth (no XAA)" />
+  <DiagramEdge from="requestor" to="idp" label="1. ID token → ID-JAG" />
+  <DiagramEdge from="requestor" to="ras" label="2. ID-JAG → access token" />
+  <DiagramEdge from="requestor" to="mcp" label="3. Bearer token" />
+</Diagram>
+
+Step by step, for a tool call to an XAA-protected upstream route:
+
+1. The MCP client connects to the gateway route with **ordinary MCP OAuth** —
+   discovery, PKCE, and a bearer token issued by the gateway. This leg is _not_
+   XAA. During the gateway's browser-login step, the user authenticates with the
+   identity provider, and the gateway captures the user's IdP identity
+   assertion.
+2. On a tool call, the gateway exchanges the user's ID token at the IdP for an
+   **ID-JAG** audience-restricted to the upstream's resource authorization
+   server (RFC 8693 token exchange).
+3. The gateway redeems the ID-JAG at the upstream resource authorization server
+   for an upstream **access token** (RFC 7523 JWT bearer grant).
+4. The gateway forwards the tool call to the upstream MCP server with
+   `Authorization: Bearer <upstream access token>` and caches the upstream token
+   per user for subsequent calls.
+
+:::note{title="In requesting-app mode, the client → gateway leg is plain OAuth"}
+
+This is the most common point of confusion. In the flow above, the MCP client
+never speaks XAA — it runs the standard MCP authorization flow against the
+gateway, and all ID-JAG exchanges happen on the gateway's _outbound_ side. A
+client doesn't need any XAA support to benefit from it.
+
+:::
+
+## What the gateway does for you
+
+In the XAA flow the gateway plays the requesting app, so the MCP client and the
+upstream MCP server are each insulated from the protocol:
+
+- **The MCP client** does nothing new. It runs the same MCP OAuth flow it would
+  for any gateway route. Claude, Cursor, ChatGPT, VS Code, and any
+  spec-compliant client work unchanged.
+- **The two-exchange dance** — the RFC 8693 token exchange at the IdP and the
+  RFC 7523 JWT-bearer redemption at the upstream — runs inside the gateway. You
+  configure endpoints and credentials; the gateway mints, redeems, caches, and
+  refreshes.
+- **Per-user identity** is preserved end to end. The IdP sees the specific user,
+  the upstream sees a token minted for that user, and gateway analytics record
+  the same subject.
+
+## Glossary
+
+- **Identity assertion** — Proof the IdP authenticated the user, carried as an
+  OIDC ID token (`urn:ietf:params:oauth:token-type:id_token`) or SAML 2.0
+  assertion. It's the _input_ to the XAA flow.
+- **ID-JAG (Identity Assertion JWT Authorization Grant)** — A short-lived signed
+  JWT the IdP mints, audience-restricted to one resource authorization server.
+  Used once to obtain an access token there. JWT header `typ: oauth-id-jag+jwt`;
+  token type `urn:ietf:params:oauth:token-type:id-jag`. It is **not** an access
+  token.
+- **Identity provider (IdP)** — The SSO authority both apps trust (Okta, Entra,
+  Auth0). In XAA it also brokers cross-app access by issuing ID-JAGs after
+  evaluating policy. Identified by `iss` in the ID-JAG.
+- **Resource authorization server** — The _target_ app's OAuth server. It
+  consumes the ID-JAG via the JWT-bearer grant and issues the real access token.
+  Identified by `aud` in the ID-JAG. In Zuplo's outbound flow, this is the
+  upstream's server, not the gateway.
+- **Requesting app** — The party that obtains and redeems the ID-JAG. When the
+  gateway fronts an XAA-protected upstream, the gateway is the requesting app.
+- **Token exchange (RFC 8693)** — The grant used at the IdP to swap the identity
+  assertion for the ID-JAG.
+- **JWT bearer grant (RFC 7523)** — The grant used at the resource authorization
+  server to redeem the ID-JAG for an access token.
+
+## When to use XAA
+
+Reach for XAA when:
+
+- An upstream MCP server is protected by an **enterprise resource authorization
+  server** that accepts ID-JAGs (the "enterprise-managed authorization"
+  pattern), and you want the gateway to broker access through your IdP rather
+  than running a separate OAuth client per upstream.
+- You need **central governance** — one place in the IdP to grant, audit, and
+  revoke which apps can reach which APIs on a user's behalf.
+
+For an upstream that uses plain per-user or shared OAuth (Linear, Notion,
+Stripe, and most SaaS MCP servers today), use
+[upstream OAuth](../auth/upstream-oauth.mdx) instead — XAA isn't required.
+
+## Try it and configure it
+
+- [Quickstart](./quickstart.mdx) — see XAA work end to end in minutes using
+  Okta's hosted [xaa.dev](https://xaa.dev) playground, with no identity tenant
+  required.
+- [Configuration reference](./policy-reference.mdx) — every `idJag` option on
+  the token-exchange policy.
+
+## Learn more
+
+- [Identity Assertion JWT Authorization Grant (IETF draft)](https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/)
+  — the ID-JAG specification. Note this is an active draft, not yet a finalized
+  RFC.
+- [MCP authorization spec](https://modelcontextprotocol.io/specification/latest/basic/authorization)
+  and the
+  [Enterprise-Managed Authorization extension](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization)
+  — where ID-JAG plugs into MCP.
+- [Okta — Cross App Access](https://developer.okta.com/blog/2025/09/03/cross-app-access)
+  — Okta's explainer and walkthrough.
+- [How the MCP Gateway works](../how-it-works.mdx) — the gateway's two OAuth
+  surfaces and request lifecycle.

package/docs/mcp-gateway/cross-app-access/policy-reference.mdx

@@ -0,0 +1,161 @@
+---
+title: "Cross App Access configuration reference"
+sidebar_label: "Configuration reference"
+description: |
+  Every configuration option for Cross App Access (XAA) on the Zuplo MCP Gateway
+  — the id-jag mode on the token-exchange policy, where the gateway acts as the
+  XAA requesting app.
+---
+
+Cross App Access is configured on the
+[`mcp-token-exchange-inbound`](#gateway-as-requesting-app) policy. Setting
+`authMode: "id-jag"` and providing an `idJag` block makes the gateway act as the
+XAA **requesting app**: it mints an ID-JAG from your IdP and redeems it at an
+upstream resource authorization server. This is the configuration the
+[quickstart](./quickstart.mdx) uses.
+
+:::note
+
+The authoritative source for these options is the policy's runtime schema. The
+generated `mcp-token-exchange-inbound` reference page predates `id-jag` mode;
+the options below reflect the runtime behavior.
+
+:::
+
+## Gateway as requesting app
+
+Set `authMode: "id-jag"` on a `mcp-token-exchange-inbound` policy and provide an
+`idJag` block. Attach the policy to the upstream route after the inbound MCP
+OAuth policy.
+
+```jsonc title="config/policies.json"
+{
+  "name": "id-jag-upstream",
+  "policyType": "mcp-token-exchange-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpTokenExchangeInboundPolicy",
+    "options": {
+      "displayName": "Upstream",
+      "authMode": "id-jag",
+      "idJag": {
+        "scopes": ["mcp:tools"],
+        "scopeDelimiter": " ",
+        "idp": {
+          "tokenUrl": "https://idp.example.com/token",
+          "clientAuth": {
+            "method": "client_secret_post",
+            "clientId": "$env(IDP_CLIENT_ID)",
+            "clientSecret": "$env(IDP_CLIENT_SECRET)",
+          },
+        },
+        "resourceAs": {
+          "tokenUrl": "https://upstream.example.com/token",
+          "audience": "https://upstream.example.com",
+          "resource": "https://upstream.example.com/mcp",
+          "clientAuth": {
+            "method": "client_secret_post",
+            "clientId": "$env(RESOURCE_AS_CLIENT_ID)",
+            "clientSecret": "$env(RESOURCE_AS_CLIENT_SECRET)",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### idJag options
+
+| Option           | Type       | Default | Description                                                          |
+| ---------------- | ---------- | ------- | -------------------------------------------------------------------- |
+| `scopes`         | `string[]` | `[]`    | Scopes requested in both exchanges.                                  |
+| `scopeDelimiter` | `string`   | `" "`   | Delimiter used to join scopes.                                       |
+| `idp`            | object     | —       | Where the gateway mints the ID-JAG (RFC 8693 token exchange).        |
+| `resourceAs`     | object     | —       | Where the gateway redeems the ID-JAG for an access token (RFC 7523). |
+
+### idp
+
+The identity provider that issues the ID-JAG.
+
+| Option       | Type   | Description                                           |
+| ------------ | ------ | ----------------------------------------------------- |
+| `tokenUrl`   | string | The IdP token endpoint.                               |
+| `clientAuth` | object | How the gateway authenticates to the IdP (see below). |
+
+### resourceAs
+
+The upstream's resource authorization server that issues the access token.
+
+| Option       | Type   | Description                                                                                                           |
+| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------- |
+| `tokenUrl`   | string | The resource authorization server's token endpoint.                                                                   |
+| `audience`   | string | **Required.** The resource AS identifier; sent as the token-exchange `audience` and becomes the ID-JAG `aud`.         |
+| `resource`   | string | Optional [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707) resource indicator. Defaults to the route's upstream URL. |
+| `clientAuth` | object | How the gateway authenticates to the resource AS (see below).                                                         |
+
+### clientAuth
+
+Both `idp.clientAuth` and `resourceAs.clientAuth` take the same shape. The
+`method` selects how the gateway authenticates:
+
+```jsonc
+// client_secret_post (or client_secret_basic)
+"clientAuth": {
+  "method": "client_secret_post",
+  "clientId": "...",
+  "clientSecret": "$env(...)"
+}
+```
+
+```jsonc
+// private_key_jwt
+"clientAuth": {
+  "method": "private_key_jwt",
+  "clientId": "...",
+  "privateKeyPem": "$env(...)",
+  "algorithm": "RS256",
+  "keyId": "...",
+  "expiresInSeconds": 300
+}
+```
+
+| Option             | Type   | Default | Applies to        | Description                                                        |
+| ------------------ | ------ | ------- | ----------------- | ------------------------------------------------------------------ |
+| `method`           | enum   | —       | all               | `client_secret_post`, `client_secret_basic`, or `private_key_jwt`. |
+| `clientId`         | string | —       | all               | The OAuth client ID.                                               |
+| `clientSecret`     | string | —       | secret methods    | The OAuth client secret.                                           |
+| `privateKeyPem`    | string | —       | `private_key_jwt` | PEM private key used to sign the client-assertion JWT.             |
+| `algorithm`        | enum   | `RS256` | `private_key_jwt` | `RS256`/`RS384`/`RS512`/`ES256`/`ES384`/`ES512`.                   |
+| `keyId`            | string | —       | `private_key_jwt` | Optional `kid` header on the client assertion.                     |
+| `audience`         | string | —       | `private_key_jwt` | Optional audience override for the client assertion.               |
+| `expiresInSeconds` | number | `300`   | `private_key_jwt` | Client-assertion lifetime, max `3600`.                             |
+
+### What the gateway does at request time
+
+On a tool call to the route, the gateway:
+
+1. Resolves the user's stored IdP identity assertion (bound during the inbound
+   browser login). If absent or expired, it returns a connect-required error and
+   refreshes the subject token when it can.
+2. Runs an RFC 8693 token exchange at `idp.tokenUrl`, requesting an ID-JAG
+   audience-restricted to `resourceAs.audience`.
+3. Redeems the ID-JAG at `resourceAs.tokenUrl` as an RFC 7523 JWT-bearer grant
+   to get the upstream access token.
+4. Caches the upstream token per user and forwards the tool call with
+   `Authorization: Bearer <upstream token>`.
+
+## Notes and limitations
+
+- The gateway issues **opaque** access tokens, not JWTs.
+- **DPoP is not supported.** Requests with a `DPoP` header are rejected.
+- XAA requires a prior inbound browser login so the gateway has an IdP identity
+  assertion to exchange.
+
+## Related
+
+- [Overview](./overview.mdx) — the protocol and the gateway's role.
+- [Quickstart](./quickstart.mdx) — a working `id-jag` configuration on the
+  playground.
+- [`mcp-token-exchange-inbound` policy](/policies/mcp-token-exchange-inbound) —
+  the base token-exchange policy reference.

package/docs/mcp-gateway/cross-app-access/quickstart.mdx

@@ -0,0 +1,330 @@
+---
+title: "Cross App Access quickstart"
+sidebar_label: "Quickstart"
+description: |
+  Build a Zuplo MCP Gateway that reaches an XAA-protected MCP server in the
+  Zuplo Portal — no repository to clone. The gateway fronts Okta's hosted
+  xaa.dev Todo0 server and performs the Cross App Access (XAA) token exchange on
+  every request.
+---
+
+This quickstart builds a working Cross App Access (XAA) gateway entirely in the
+Zuplo Portal. An MCP client connects to the gateway with ordinary OAuth; the
+gateway then performs the XAA token exchange against
+[Okta's hosted xaa.dev playground](https://xaa.dev) and reaches the protected
+Todo0 MCP server on the user's behalf.
+
+There is no repository to clone and no identity tenant to stand up. Everything
+runs in the portal against the public xaa.dev playground.
+
+## Why xaa.dev
+
+[xaa.dev](https://xaa.dev) is Okta's hosted Cross App Access playground: a
+public identity provider, resource authorization server, and Todo0 MCP server
+that are already wired together for the XAA token exchange. Standing up your own
+XAA stack means provisioning an IdP, a resource authorization server, and a
+protected MCP server — and configuring the trust relationships between all
+three. The playground gives you all of that for free, so today it's the fastest
+way to see a real Cross App Access flow end to end. Once the gateway works
+against xaa.dev, swapping in your own identity provider and upstream is just a
+change of endpoints and credentials.
+
+## What you'll build
+
+A single gateway route with two policies does all the work:
+
+- An **MCP OAuth** policy (`mcp-oauth-inbound`) secures the client → gateway
+  leg. The client authenticates to the gateway with plain MCP OAuth — this leg
+  is not XAA.
+- A **token-exchange** policy (`mcp-token-exchange-inbound`) in `id-jag` mode
+  performs the outbound XAA exchange to the upstream: it mints an ID-JAG at the
+  playground identity provider (IdenX), redeems it at the resource authorization
+  server, and calls the Todo0 MCP server with the resulting access token.
+
+The XAA exchange happens entirely on the gateway's outbound side. See
+[the overview](./overview.mdx#how-the-flow-works) for the full sequence.
+
+## Prerequisites
+
+- A [Zuplo account](https://portal.zuplo.com)
+- A free account on [xaa.dev](https://xaa.dev)
+- [MCP Jam](https://www.mcpjam.com) — a browser-based MCP client used to drive
+  the flow. Any MCP client that supports OAuth works.
+
+## Steps
+
+<Stepper>
+
+1. **Create a Zuplo project.**
+
+   In the [Zuplo Portal](https://portal.zuplo.com/+/account/projects), select
+   **New Project** and create an empty **API Gateway** project. Name it
+   `xaa-quick-start`.
+
+   On the project **Overview** page, copy the deployment URL shown at the top
+   (for example, `https://xaa-quick-start-main-abc1234.d2.zuplo.dev`). This is
+   your gateway's public origin — you'll need it for the next two steps.
+
+   :::note
+
+   Throughout this guide, replace `https://your-gateway.zuplo.dev` with your
+   project's actual deployment URL.
+
+   :::
+
+2. **Register a requesting app on xaa.dev.**
+
+   Sign in to [xaa.dev](https://xaa.dev) and open
+   [the developer registration page](https://xaa.dev/developer/register). Enter
+   your email, then select **Register New App** and fill in:
+   - **Application Name** — anything, for example `xaa-quick-start gateway`.
+   - **Redirect URIs** — your gateway's OAuth callback:
+
+     ```text
+     https://your-gateway.zuplo.dev/__zuplo/oauth/callback
+     ```
+
+   Under **Resource Connections**, select **Todo0 MCP Server**, keep both scopes
+   (`todos.read` and `mcp.access`) checked, and select **Add Connection**. Then
+   select **Register App**.
+
+   <BrowserScreenshot url="https://xaa.dev/developer/register">
+
+   ![Registered requesting app on xaa.dev](../../../public/media/cross-app-access/xaa-playground.png)
+
+   </BrowserScreenshot>
+
+   Registration shows four values. Copy all of them — the secrets are shown only
+   once:
+
+   | xaa.dev value          | Used for                        |
+   | ---------------------- | ------------------------------- |
+   | Client ID              | `XAA_CLIENT_ID`                 |
+   | Client Secret          | `XAA_CLIENT_SECRET`             |
+   | Resource Client ID     | `XAA_RESOURCE_AS_CLIENT_ID`     |
+   | Resource Client Secret | `XAA_RESOURCE_AS_CLIENT_SECRET` |
+
+   :::tip
+
+   The playground identity provider (IdenX) accepts any email with no password,
+   so you can sign in as any test user when you drive the flow.
+
+   :::
+
+3. **Add the gateway configuration.**
+
+   Open the project's code editor (the **Code** tab). The gateway needs three
+   files.
+
+   First, define the two policies. Open `config/policies.json` (use the raw
+   `policies.json` tab, not the visual Policy List) and replace its contents:
+
+   ```json title="config/policies.json"
+   {
+     "policies": [
+       {
+         "name": "xaa-inbound",
+         "policyType": "mcp-oauth-inbound",
+         "handler": {
+           "module": "$import(@zuplo/runtime/mcp-gateway)",
+           "export": "McpOAuthInboundPolicy",
+           "options": {
+             "oidc": {
+               "issuer": "https://idp.xaa.dev",
+               "jwksUrl": "https://idp.xaa.dev/jwks",
+               "audience": "$env(GATEWAY_AUDIENCE)"
+             },
+             "browserLogin": {
+               "url": "https://idp.xaa.dev/authorize",
+               "tokenUrl": "https://idp.xaa.dev/token",
+               "clientId": "$env(XAA_CLIENT_ID)",
+               "clientSecret": "$env(XAA_CLIENT_SECRET)",
+               "scope": "openid profile email",
+               "audience": "$env(GATEWAY_AUDIENCE)",
+               "pkce": "S256"
+             }
+           }
+         }
+       },
+       {
+         "name": "id-jag-upstream",
+         "policyType": "mcp-token-exchange-inbound",
+         "handler": {
+           "module": "$import(@zuplo/runtime/mcp-gateway)",
+           "export": "McpTokenExchangeInboundPolicy",
+           "options": {
+             "id": "id-jag-upstream",
+             "displayName": "Todo0",
+             "summary": "xaa.dev Todo0 MCP server, reached via Cross App Access (ID-JAG).",
+             "authMode": "id-jag",
+             "idJag": {
+               "scopes": ["todos.read", "mcp.access"],
+               "idp": {
+                 "tokenUrl": "https://idp.xaa.dev/token",
+                 "clientAuth": {
+                   "method": "client_secret_post",
+                   "clientId": "$env(XAA_CLIENT_ID)",
+                   "clientSecret": "$env(XAA_CLIENT_SECRET)"
+                 }
+               },
+               "resourceAs": {
+                 "tokenUrl": "https://auth.resource.xaa.dev/token",
+                 "audience": "https://auth.resource.xaa.dev",
+                 "resource": "https://mcp.xaa.dev/mcp",
+                 "clientAuth": {
+                   "method": "client_secret_post",
+                   "clientId": "$env(XAA_RESOURCE_AS_CLIENT_ID)",
+                   "clientSecret": "$env(XAA_RESOURCE_AS_CLIENT_SECRET)"
+                 }
+               }
+             }
+           }
+         }
+       }
+     ]
+   }
+   ```
+
+   The IdP, resource authorization server, and upstream endpoints are wired to
+   the playground here. Only the credentials and the gateway audience are
+   environment-driven, so you can plug in your own xaa.dev app. For every
+   option, see the [configuration reference](./policy-reference.mdx).
+
+   Next, add the route that exposes the gateway. Open `config/routes.oas.json`
+   (the raw `routes.oas.json` tab) and replace its contents:
+
+   ```json title="config/routes.oas.json"
+   {
+     "openapi": "3.1.0",
+     "info": {
+       "version": "1.0.0",
+       "title": "XAA MCP Gateway",
+       "description": "MCP gateway that bridges to the xaa.dev Todo0 MCP server via Cross App Access (ID-JAG)."
+     },
+     "paths": {
+       "/mcp/todo0": {
+         "post": {
+           "operationId": "todo0Bridge",
+           "summary": "Bridge to the xaa.dev Todo0 MCP server",
+           "x-zuplo-route": {
+             "corsPolicy": "none",
+             "handler": {
+               "module": "$import(@zuplo/runtime/mcp-gateway)",
+               "export": "McpProxyHandler",
+               "options": {
+                 "rewritePattern": "https://mcp.xaa.dev/mcp"
+               }
+             },
+             "policies": {
+               "inbound": ["xaa-inbound", "id-jag-upstream"]
+             }
+           }
+         }
+       }
+     }
+   }
+   ```
+
+   The `McpProxyHandler` forwards the request to the upstream Todo0 server, and
+   both policies run inbound — first the MCP OAuth check, then the XAA exchange.
+
+   Finally, register the MCP Gateway plugin. In the file tree, right-click the
+   `modules` folder, select **New Runtime Extension**, and replace the generated
+   file's contents:
+
+   ```typescript title="modules/zuplo.runtime.ts"
+   import { RuntimeExtensions } from "@zuplo/runtime";
+   import { McpGatewayPlugin } from "@zuplo/runtime/mcp-gateway";
+
+   // Registers the MCP Gateway, which adds the OAuth and upstream-connection
+   // routes used to expose and secure MCP servers through your gateway.
+   // Docs: https://zuplo.com/docs/mcp-server/introduction
+   export function runtimeInit(runtime: RuntimeExtensions) {
+     runtime.addPlugin(new McpGatewayPlugin());
+   }
+   ```
+
+   Save each file. The build fails until the environment variables exist —
+   that's the next step.
+
+4. **Set the environment variables.**
+
+   Open **Settings →
+   [Environment Variables](https://portal.zuplo.com/+/account/project/settings/environment-variables)**
+   and add each variable below with **Add variable**. Mark the two `*_SECRET`
+   values as **Secret** so they're encrypted and hidden after saving. Leave all
+   three environments (Production, Preview, Development) selected.
+
+   | Variable                        | Value                                                                         | Secret |
+   | ------------------------------- | ----------------------------------------------------------------------------- | ------ |
+   | `GATEWAY_AUDIENCE`              | Your gateway's deployment URL (for example, `https://your-gateway.zuplo.dev`) | No     |
+   | `XAA_CLIENT_ID`                 | Client ID from the xaa.dev app                                                | No     |
+   | `XAA_CLIENT_SECRET`             | Client Secret from the xaa.dev app                                            | Yes    |
+   | `XAA_RESOURCE_AS_CLIENT_ID`     | Resource Client ID from the Todo0 connection                                  | No     |
+   | `XAA_RESOURCE_AS_CLIENT_SECRET` | Resource Client Secret from the Todo0 connection                              | Yes    |
+
+   Saving an environment variable triggers a new deployment. Once it finishes,
+   the gateway is live.
+
+5. **Connect with MCP Jam and list the todos.**
+
+   Open the [MCP Jam web inspector](https://www.mcpjam.com), go to **Connect**,
+   and select **Add Server**:
+   - **Server Name** — `xaa-quick-start`
+   - **Connection Type** — `HTTPS`, with the route URL
+     `https://your-gateway.zuplo.dev/mcp/todo0`
+   - **Authentication** — `OAuth`
+
+   <ModalScreenshot>
+
+   ![Add the gateway as an MCP server in MCP Jam](../../../public/media/cross-app-access/add-mcp-server.png)
+
+   </ModalScreenshot>
+
+   Select **Add Server**. MCP Jam starts the OAuth flow and redirects you to
+   sign in. Sign in at the IdenX screen (any email, no password) and approve the
+   consent screen. MCP Jam returns to the inspector and the server shows as
+   **Connected**.
+
+   <Framed>
+
+   ![The gateway connected in MCP Jam](../../../public/media/cross-app-access/connected-card.png)
+
+   </Framed>
+
+   Open the **Resources** panel and select **List all todos**. The todos come
+   back as JSON — the agent never touched the XAA protocol. Behind the scenes
+   the gateway minted an ID-JAG from the playground IdP, redeemed it at the
+   resource authorization server, and called the Todo0 MCP server with the
+   resulting access token.
+
+   <Framed>
+
+   ![Todo0 resources and todos returned through the gateway in MCP Jam](../../../public/media/cross-app-access/todo-resources.png)
+
+   </Framed>
+
+</Stepper>
+
+## Verify from the command line (optional)
+
+To confirm the gateway is deployed and secured without a client, check its OAuth
+metadata and the protected route:
+
+```bash
+# Protected-resource metadata is published for the route (expect 200)
+curl -s https://your-gateway.zuplo.dev/.well-known/oauth-protected-resource/mcp/todo0
+
+# The MCP route rejects unauthenticated calls (expect 401)
+curl -s -o /dev/null -w "%{http_code}\n" -X POST \
+  https://your-gateway.zuplo.dev/mcp/todo0 \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1.0.0"}}}'
+```
+
+## Next steps
+
+- [Configuration reference](./policy-reference.mdx) — the full `idJag` option
+  set.
+- [Overview](./overview.mdx) — the protocol and the gateway's role explained.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.71.10",
+  "version": "6.71.12",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.71.10",
-    "@zuplo/core": "6.71.10",
-    "@zuplo/runtime": "6.71.10",
+    "@zuplo/cli": "6.71.12",
+    "@zuplo/core": "6.71.12",
+    "@zuplo/runtime": "6.71.12",
     "@zuplo/test": "1.4.0"
   }
 }