zuplo 6.73.26 → 6.73.27

package/docs/articles/workload-identity-inbound.mdx

@@ -0,0 +1,359 @@
+---
+title: Authenticate a cloud workload identity
+sidebar_label: Cloud Workload Identity
+description:
+  Verify the OIDC identity token a GCP, AWS, or Azure workload mints from its
+  own ambient credentials, then pin the route to the workloads you allow.
+tags:
+  - authentication
+---
+
+A workload running in a cloud already has an identity: a Google service account,
+a Kubernetes service account on EKS or AKS. On most of those platforms it can
+get a short-lived OIDC identity token for that identity — minted on demand by
+the metadata server on GCP, projected into the pod on EKS and AKS. The caller
+then authenticates to your gateway without anyone creating, distributing, or
+rotating a new secret.
+
+Zuplo has no dedicated GCP or Azure inbound JWT policy, and no inbound AWS SigV4
+verification policy. The path that works is the generic
+[Open ID JWT Auth](../policies/open-id-jwt-auth-inbound.mdx) policy pointed at
+the cloud's OIDC issuer, followed by
+[Require User Claims](../policies/require-user-claims-inbound.mdx) to decide
+which of that issuer's identities may call the route.
+
+## How it works
+
+1. The caller asks its platform for an identity token for a fixed audience
+   string.
+2. The JWT policy validates the signature against the issuer's JWKS, checks the
+   `iss` and `aud` claims, and populates `request.user`.
+3. A claims policy allows only the identities on your allowlist and returns
+   `403` to everything else.
+4. Later policies (rate limits, quotas, logging) group on the identity that step
+   2 established.
+
+Step 3 isn't optional. Every Google customer's workloads share the issuer
+`https://accounts.google.com`, so on GCP the issuer check alone proves only that
+_someone's_ Google service account made the call. The audience check and the
+claims allowlist are what narrow that to your workloads. A cluster issuer on EKS
+or AKS is already yours, but the claims rule is still what separates one
+namespace or service account from every other one on the cluster.
+
+## Prerequisites
+
+- A Zuplo project with at least one route.
+- A caller running on a platform that issues OIDC identity tokens for its own
+  workload identity: Compute Engine, GKE, Cloud Run, or Cloud Build on GCP; EKS
+  with IAM Roles for Service Accounts or EKS Pod Identity on AWS; AKS workload
+  identity on Azure.
+- Access to set an [environment variable](./environment-variables.mdx) on the
+  project.
+
+## 1/ Settle on a fixed audience
+
+The gateway's job is to require one exact `aud` value. Settle on that value
+first, and store it as an environment variable assigned to every environment:
+
+```
+GATEWAY_AUDIENCE=https://api.example.com/agents
+```
+
+Changing an environment variable requires a new deployment, so treat this value
+as stable configuration rather than something to tune per branch.
+
+How much freedom you have in choosing it belongs to the caller's platform, not
+to the gateway. On GCP the caller passes any audience it likes as a query
+parameter, per call. On EKS and AKS the audience is fixed on the projected-token
+volume, so it is chosen once at deploy time — on AKS it defaults to
+`api://AzureADTokenExchange`. On a token issued by Microsoft Entra ID it has to
+be a registered Application ID URI, in the form `api://<app-client-id>`. Where
+the platform constrains the value, the gateway's `audience` has to match what
+the platform already issues rather than a value you invent.
+
+:::caution{title="Keep the audience decoupled from the deployment URL"}
+
+Where you do get to choose, reusing the deployment URL as the audience looks
+tidy until the first preview build. Every branch deployment gets its own
+hostname, so every branch would need its own audience, its own caller-side
+configuration, and a redeploy to change. One constant that never varies across
+environments keeps a single caller configuration working everywhere.
+
+:::
+
+## 2/ Mint a token in the caller
+
+On GCP, a workload reads an identity token straight from the metadata server,
+with no SDK and no `gcloud` install required:
+
+```bash
+AUDIENCE="https://api.example.com/agents"
+
+TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
+  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=${AUDIENCE}")
+
+curl -H "Authorization: Bearer ${TOKEN}" \
+  https://my-api-main-abc123.zuplo.app/agents/ping
+```
+
+The decoded payload of a service account identity token looks like this:
+
+```json
+{
+  "aud": "https://api.example.com/agents",
+  "azp": "112010400000000710080",
+  "email": "batch-runner@my-project.iam.gserviceaccount.com",
+  "email_verified": true,
+  "exp": 1745365618,
+  "iat": 1745362018,
+  "iss": "https://accounts.google.com",
+  "sub": "112010400000000710080"
+}
+```
+
+Two claims carry the caller's identity, and they are not interchangeable. `sub`
+is the service account's immutable numeric unique ID. `email` is its address,
+which is what a reviewer recognizes when reading an allowlist six months later.
+Pick whichever your review process prefers, or match on either with an `or`
+rule.
+
+:::tip{title="Getting a token on a workstation"}
+
+For local development,
+`gcloud auth print-identity-token --audiences="$AUDIENCE"` prints the same kind
+of token. Pass `--audiences` explicitly: without it you get a token with an
+audience the gateway is not configured to accept, and a `401` that looks like a
+signature problem. Add `--include-email` when printing a token for an
+impersonated service account, otherwise the token carries no `email` claim and
+an email allowlist rejects it.
+
+:::
+
+### Other clouds
+
+| Platform                                                           | Where the caller gets the token                                           | `issuer`                                                                              | `jwkUrl`                                                       |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| GCP service accounts (Compute Engine, GKE, Cloud Run, Cloud Build) | Metadata server identity endpoint, with the audience as a query parameter | `https://accounts.google.com`                                                         | `https://www.googleapis.com/oauth2/v3/certs`                   |
+| AWS EKS (IAM Roles for Service Accounts, EKS Pod Identity)         | Projected service account token, with the audience set on the volume      | The cluster's OIDC issuer URL                                                         | The `jwks_uri` from the issuer's OpenID configuration document |
+| AKS workload identity                                              | Projected service account token, with the audience set on the volume      | The cluster's OIDC issuer URL, from `az aks show --query oidcIssuerProfile.issuerUrl` | The `jwks_uri` from the issuer's OpenID configuration document |
+
+On both EKS and AKS the token the pod receives is the cluster's own projected
+service account token, so the subject is the Kubernetes service account —
+`system:serviceaccount:<namespace>:<name>` — and the issuer is the cluster, not
+the cloud's identity provider. A token issued by Microsoft Entra ID is a
+different thing: getting one means the workload first exchanges its projected
+token for an Entra token, its `aud` has to be a registered Application ID URI,
+and its `sub` is an object-ID GUID rather than anything human-readable.
+Verifying the cluster-issued token directly is the shorter path, and it is the
+one this guide follows.
+
+For any issuer other than Google, read `jwks_uri` out of the issuer's
+`/.well-known/openid-configuration` document rather than guessing the path.
+
+## 3/ Verify the token at the gateway
+
+```json title="config/policies.json"
+{
+  "name": "workload-identity-auth",
+  "policyType": "open-id-jwt-auth-inbound",
+  "handler": {
+    "export": "OpenIdJwtInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "issuer": "https://accounts.google.com",
+      "audience": "$env(GATEWAY_AUDIENCE)",
+      "jwkUrl": "https://www.googleapis.com/oauth2/v3/certs"
+    }
+  }
+}
+```
+
+Set `audience`. The option is optional in the schema and load-bearing in
+practice: without it, every service account identity token Google issues — for
+any project, aimed at any service — satisfies the policy.
+
+Leave `allowUnauthenticatedRequests` unset. It defaults to `false`, which
+returns `401` for a missing, expired, or wrong-audience token. Setting it to
+`true` lets that request continue down the pipeline with no `request.user`
+attached, and everything that depends on an identity then degrades quietly
+rather than failing: `rateLimitBy: "user"` falls back to a single shared
+`user-anonymous` bucket, so every unauthenticated caller competes for one
+counter and any one of them can exhaust it for all the others. The route is then
+only as closed as the next policy or the handler makes it. Set it to `true` only
+in a deliberate fallback arrangement, where a second authentication policy runs
+after this one. See [Multiple Auth Policies](./multiple-auth-policies.mdx) for
+that pattern.
+
+## 4/ Pin which workloads may call the route
+
+The JWT policy proves the caller holds a token from the issuer. The claims
+policy decides which callers that covers. Match on a claim the token actually
+carries: `email` exists on GCP service account identity tokens, and a projected
+Kubernetes service account token has no `email` claim at all.
+
+```json title="config/policies.json"
+{
+  "name": "allow-known-workloads",
+  "policyType": "require-user-claims-inbound",
+  "handler": {
+    "export": "RequireUserClaimsInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "rule": {
+        "claim": "email",
+        "in": [
+          "batch-runner@my-project.iam.gserviceaccount.com",
+          "report-agent@my-project.iam.gserviceaccount.com"
+        ]
+      }
+    }
+  }
+}
+```
+
+This policy runs after an authentication policy, never instead of one. With no
+authenticated user on the request it returns `401`; when the rule evaluates to
+false it returns `403` without echoing claim values, and writes the failing
+checks to the request log instead.
+
+On EKS and AKS the subject is the Kubernetes service account,
+`system:serviceaccount:<namespace>:<name>`, so a namespace prefix pins every
+workload in one namespace at once:
+
+```json
+{
+  "rule": {
+    "claim": "sub",
+    "startsWith": "system:serviceaccount:agents:"
+  }
+}
+```
+
+`startsWith` also covers AWS STS-issued tokens, whose subject is an assumed-role
+ARN such as `arn:aws:sts::123456789012:assumed-role/my-role/<session>` — a
+prefix match is the only workable rule there, because the trailing session name
+changes on every call. That is a different token from the projected service
+account token an EKS pod holds, so check which one your caller actually sends
+before writing the rule.
+
+For namespaced claims, array-valued group claims, and `and`/`or` nesting, see
+the [Require User Claims](../policies/require-user-claims-inbound.mdx) policy
+reference.
+
+## 5/ Rate limit per identity
+
+```json title="config/policies.json"
+{
+  "name": "rate-limit-per-workload",
+  "policyType": "rate-limit-inbound",
+  "handler": {
+    "export": "RateLimitInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "rateLimitBy": "user",
+      "requestsAllowed": 600,
+      "timeWindowMinutes": 1
+    }
+  }
+}
+```
+
+`rateLimitBy: "user"` groups on `request.user.sub`, which the authentication
+policy earlier in the pipeline populates, so nothing here is specific to JWTs.
+For Google tokens that subject is the numeric unique ID; set
+`subPropertyName: "email"` on the JWT policy if you would rather the subject,
+and therefore the rate limit bucket, carry the readable service account address.
+
+[Rate Limiting](../policies/rate-limit-inbound.mdx) is available on every plan.
+[Complex Rate Limiting](../policies/complex-rate-limit-inbound.mdx), which
+counts several resources per request, is an Enterprise policy.
+
+## 6/ Attach the policies to the route
+
+Nothing above takes effect until the three policies are listed on the route, in
+pipeline order — authenticate, then authorize, then meter:
+
+```json title="config/routes.oas.json (excerpt)"
+{
+  "x-zuplo-route": {
+    "policies": {
+      "inbound": [
+        "workload-identity-auth",
+        "allow-known-workloads",
+        "rate-limit-per-workload"
+      ]
+    }
+  }
+}
+```
+
+:::note
+
+Per-request structured logging works on every plan through `context.log.info`
+and `context.log.setLogProperties` — see [Logging](./logging.mdx) — so the
+allowed identity can appear on the log line for the call it authorized. The
+[Audit Log](../policies/audit-log-inbound.mdx) policy, which emits a CloudEvents
+audit trail, is an Enterprise policy on top of that.
+
+:::
+
+## 7/ Verify it worked
+
+Run all three cases against the deployed route:
+
+```bash
+# 1. A token for the configured audience, from an allowlisted identity: 200.
+curl -o /dev/null -w "%{http_code}\n" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  https://my-api-main-abc123.zuplo.app/agents/ping
+
+# 2. A token minted for a different audience: 401.
+OTHER=$(curl -s -H "Metadata-Flavor: Google" \
+  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.example.com/other")
+curl -o /dev/null -w "%{http_code}\n" \
+  -H "Authorization: Bearer ${OTHER}" \
+  https://my-api-main-abc123.zuplo.app/agents/ping
+
+# 3. No token at all: 401.
+curl -o /dev/null -w "%{http_code}\n" \
+  https://my-api-main-abc123.zuplo.app/agents/ping
+```
+
+A token from a workload that is not on the allowlist returns `403` rather than
+`401` — the signature and audience were fine, the identity was not. That
+distinction is the fastest way to tell a caller-configuration problem from an
+authorization problem.
+
+## Limitations
+
+- **No inbound AWS SigV4 verification policy.** Verifying a SigV4-signed request
+  means writing the verification in
+  [Custom Code](../policies/custom-code-inbound.mdx). This matters on platforms
+  where the ambient AWS credential is a signature rather than an OIDC token — a
+  plain EC2 instance or a Lambda function, for example. The outbound direction
+  has policies for it:
+  [AWS service auth](../policies/upstream-aws-service-auth-inbound.mdx) and
+  [AWS federated auth](../policies/upstream-aws-federated-auth-inbound.mdx) are
+  both Enterprise features and both in beta, and they are free to try in
+  development. Neither sets an `Authorization` header on its own — SigV4 signs
+  the exact final request, which is only known inside the handler, so the
+  policies resolve the credentials and the `awsLambdaHandler` or your own code
+  signs the request with `AwsClient.fromContext(context)`.
+- **No dedicated GCP or Azure inbound JWT policy.** Zuplo ships
+  provider-specific inbound JWT policies for identity providers — Auth0, Okta,
+  Clerk, Firebase, Supabase, Cognito user pools — but none for cloud workload
+  identity. The generic OIDC policy covers it, which means you supply `issuer`
+  and `jwkUrl` yourself instead of picking a provider from a list.
+- **Token lifetime belongs to the platform.** Mint a token per call or hold it
+  only in memory; never write one into configuration or a stored secret.
+
+## Additional resources
+
+- [Authentication](../concepts/authentication.mdx) — every inbound
+  authentication method Zuplo supports and how `request.user` is populated.
+- [Rate limiting](../rate-limiting/getting-started.mdx) — the full set of
+  identification strategies, including dynamic per-caller limits.
+- [Request user](../programmable-api/request-user.mdx) — reading the
+  authenticated identity and its claims in a handler.
+- [Securing your backend](./securing-your-backend.mdx) — the other half of the
+  request: how the gateway authenticates itself to your origin.

package/docs/build-with-ai.mdx

@@ -18,12 +18,21 @@ The `zuplo` npm package ships the full documentation at
 your project. An `AGENTS.md` file at the repo root tells agents to read those
 docs before writing any code — no network calls required.
 
-New projects scaffold both files automatically:
+New projects get the bundled docs with the `zuplo` package, and
+[`create-zuplo-api`](./cli/create-zuplo-api.mdx) asks which coding agents to
+configure. Pick **OpenAI Codex** for an `AGENTS.md`, or name the agents up
+front:
 
 ```bash
-npx create-zuplo-api@latest
+npx create-zuplo-api@latest --agents codex
 ```
 
+Each agent gets the instruction file it reads natively — `AGENTS.md` for Codex,
+`CLAUDE.md` for Claude Code, `.cursorrules` for Cursor — plus a shared
+`.mcp.json`. See
+[Configuring AI coding agents](./cli/create-zuplo-api.mdx#configuring-ai-coding-agents)
+for the full list.
+
 For existing projects on `zuplo` 0.66.0 or later, drop in the default
 `AGENTS.md`:
 

package/docs/cli/create-zuplo-api.mdx

@@ -28,7 +28,16 @@ npx create-zuplo-api@latest
 - `--git` - Whether or not to initialize the project as a git repository
 - `--version-check` - Whether or not to check for an outdated version
 - `--install` - Whether or not to install packages
+- `--verbose` - Enable verbose logging
 - `--yes` - Use saved preferences or defaults for unprovided options
+- `--server-project` - Create a matching project on portal.zuplo.com and link
+  this working copy to it, skipping the interactive prompt. See
+  [Creating a matching portal project](#creating-a-matching-portal-project)
+- `--account <account-name>` - The Zuplo account that will host the server
+  project. Implies `--server-project`
+- `--agents <agents>` - Comma-separated list of AI coding agents to configure
+  (`claude`, `copilot`, `cursor`, `windsurf`, `codex`), or `none` to skip agent
+  setup. See [Configuring AI coding agents](#configuring-ai-coding-agents)
 - `-e, --example <example-name|github-url>` - An example to bootstrap the API
   with. You can use an example name from the official Zuplo repository or a
   public GitHub URL. The URL can use any branch and/or subdirectory
@@ -38,27 +47,151 @@ npx create-zuplo-api@latest
   the example separately: `--example-path foo/bar`
 - `-h, --help` - Display the help message
 
-### Examples
+### Opting out with `--no-` flags
+
+Each boolean option also accepts a `--no-` form that turns the feature off:
+
+| Opt-out flag          | Effect                                              |
+| --------------------- | --------------------------------------------------- |
+| `--no-eslint`         | Skip ESLint configuration                           |
+| `--no-prettier`       | Skip Prettier configuration                         |
+| `--no-git`            | Don't initialize the project as a git repository    |
+| `--no-install`        | Don't install packages                              |
+| `--no-version-check`  | Don't check for an outdated version                 |
+| `--no-server-project` | Don't create a matching project on portal.zuplo.com |
+
+These flags matter most in CI and scripted use. `--yes` accepts whatever is
+saved in your preferences for any option you didn't pass, so a value you chose
+once on a workstation can carry into a later run. A `--no-` flag ignores saved
+preferences and suppresses the prompt outright, which makes the result the same
+on every machine:
+
+```bash
+npx create-zuplo-api@latest my-api --yes --no-eslint --no-prettier --no-install --no-git
+```
+
+If you pass both spellings of the same option, the affirmative flag wins — so
+`--eslint --no-eslint` initializes ESLint. `--no-server-project` is the
+exception: it always wins, even when combined with `--server-project` or
+`--account`.
+
+### Configuring AI coding agents
+
+Pass `--agents` to write instruction files and MCP configuration for the coding
+agents you use. Each selected agent also gets the
+[Zuplo agent skills](../build-with-ai.mdx#agent-skills), so it works from
+accurate Zuplo documentation instead of training data. Claude Code enables them
+through the `zuplo/tools` plugin marketplace in `.claude/settings.json`. For
+every other agent, the CLI downloads the skill files into that agent's skills
+directory, such as `.cursor/skills/`.
+
+| Value      | Agent          | Files written                                     |
+| ---------- | -------------- | ------------------------------------------------- |
+| `claude`   | Claude Code    | `CLAUDE.md`, `.claude/settings.json`, `.mcp.json` |
+| `copilot`  | GitHub Copilot | `.github/copilot-instructions.md`, `.mcp.json`    |
+| `cursor`   | Cursor         | `.cursorrules`, `.mcp.json`                       |
+| `windsurf` | Windsurf       | `.windsurfrules`, `.mcp.json`                     |
+| `codex`    | OpenAI Codex   | `AGENTS.md`, `.mcp.json`                          |
+| `none`     | —              | Nothing — skips agent setup                       |
+
+Combine values with commas:
+
+```bash
+npx create-zuplo-api@latest my-api --agents claude,cursor
+```
+
+The CLI validates the list before scaffolding anything:
+
+- An unrecognized agent name is an error. `--agents zed` fails and prints the
+  valid values.
+- `none` can't be combined with a real agent. Use `--agents none` to skip agent
+  setup, or list only the agents you want.
+
+## Creating a matching portal project
+
+By default, the CLI asks whether to create a matching project on
+portal.zuplo.com and link your new working copy to it. Answering yes runs
+`zuplo project create` and `zuplo link`, which creates the project in your Zuplo
+account and writes `ZUPLO_ACCOUNT_NAME` and `ZUPLO_PROJECT_NAME` to a
+`.env.zuplo` file in the project directory. The CLI then prints the portal URL
+for the new project.
+
+Pass `--server-project` to opt in without the prompt, or `--account <name>` to
+also choose which account hosts the project:
+
+```bash
+npx create-zuplo-api@latest my-api --account my-account
+```
+
+Creating the project requires authentication. Run
+[`zuplo login`](./authentication.mdx) first, or let `zuplo project create` walk
+you through signing in. When you have access to exactly one account, the CLI
+picks it automatically; with more than one and no `--account`, it asks which
+account should host the project.
+
+To keep everything local, pass `--no-server-project`:
+
+```bash
+npx create-zuplo-api@latest my-api --no-server-project
+```
+
+:::note
+
+`--yes` and CI environments skip this step unless you pass `--server-project` or
+`--account`. Unlike the other prompts, the answer isn't saved to your
+preferences, so a yes on your workstation never becomes a yes in CI.
+
+:::
+
+In non-interactive runs the CLI can't ask which account to use. Unless your
+credentials resolve to exactly one account, pair `--server-project` with
+`--account`. Otherwise the CLI prints a note, leaves your local files in place,
+and skips the portal project:
+
+```bash
+npx create-zuplo-api@latest my-api --yes --account my-account
+```
+
+If project creation or linking fails, the scaffolded files stay on disk and the
+CLI tells you how to finish up — run `zuplo project create --name my-api` and
+`zuplo link` from inside the project directory.
+
+## Examples
 
 The following examples show different ways to use `create-zuplo-api`:
 
-#### With Default Template
+### With Default Template
 
 ```bash
-npx create-zuplo-api@latest my-api
-cd my-api
-npm run dev
+npx create-zuplo-api@latest
 ```
 
-You will then be asked the following prompts:
+The CLI asks the following questions:
+
+```text
+? What is your project named? › my-api
+? Create a matching project on portal.zuplo.com? › No / Yes
+? Would you like to use ESLint? › No / Yes
+? Would you like to use Prettier? › No / Yes
+? Which AI coding agents would you like to configure? › - Space to select. Return to submit
+◯   Claude Code
+◯   GitHub Copilot
+◯   Cursor
+◯   Windsurf
+◯   OpenAI Codex
+◯   None
+```
+
+Pass the directory as an argument to skip the first question, then start the
+development server:
 
 ```bash
-What's your project named? my-api
-Would you like to use ESLint? No / Yes
-Would you like to use Prettier? No / Yes
+npx create-zuplo-api@latest my-api
+cd my-api
+npm run dev
 ```
 
-#### With an Official Example from GitHub
+### With an Official Example from GitHub
 
 To create a new Zuplo API using an official example from the Zuplo GitHub
 repository, you specify the example name using the `--example` option.
@@ -70,7 +203,11 @@ npx create-zuplo-api@latest my-api --example my-example
 You can find the list of available examples in the
 [Zuplo examples repository](https://github.com/zuplo/zuplo/tree/main/examples).
 
-#### With any Public GitHub Repository
+Examples ship their own linting, formatting, and agent configuration, so the
+CLI skips those questions. It still asks about creating a matching project on
+portal.zuplo.com, because that choice is independent of the template.
+
+### With any Public GitHub Repository
 
 To create a new Zuplo API using any public GitHub repository, you can specify
 the repository URL using the `--example` option.

package/docs/cli/overview.mdx

@@ -75,4 +75,6 @@ For a complete list of commands and flags, run `zuplo --help` or see
 [Global Options](./global-options.mdx).
 
 To scaffold a new project without installing the CLI, see
-[create-zuplo-api](./create-zuplo-api.mdx).
+[create-zuplo-api](./create-zuplo-api.mdx). It can also run `project create` and
+`link` for you, so a new working copy comes out already connected to a project on
+portal.zuplo.com.

package/docs/concepts/upstream-credentials.mdx

@@ -0,0 +1,193 @@
+---
+title: Upstream Credentials
+---
+
+Every request that passes through Zuplo involves two separate authentication
+decisions. The caller authenticates to the gateway, and the gateway
+authenticates to whatever it calls next. The two rarely use the same credential,
+and on most routes they don't even use the same scheme: a client might present a
+Zuplo API key while the upstream expects an AWS SigV4 signature, a Google ID
+token, or a vendor API key in a query string.
+
+[Authentication](./authentication.mdx) covers the first decision. This page
+covers the second — which credential the gateway attaches on the way out, which
+policy attaches it, and where the credential itself lives.
+
+## Two directions, one request
+
+An upstream credential is attached in the middle of the request pipeline, after
+the caller's identity is known and before the request leaves for the origin.
+
+<Diagram height="h-96">
+  <DiagramNode id="caller">Caller</DiagramNode>
+  <DiagramGroup id="zuplo" label="Zuplo API Gateway">
+    <DiagramNode id="verify" variant="zuplo">
+      Verify caller credential
+    </DiagramNode>
+    <DiagramNode id="enforce" variant="zuplo">
+      Authorize, rate limit, log
+    </DiagramNode>
+    <DiagramNode id="attach" variant="zuplo">
+      Attach upstream credential
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramNode id="upstream">Upstream</DiagramNode>
+  <DiagramEdge from="caller" to="zuplo" />
+  <DiagramEdge from="verify" to="enforce" fromSide="bottom" toSide="top" />
+  <DiagramEdge from="enforce" to="attach" fromSide="bottom" toSide="top" />
+  <DiagramEdge from="zuplo" to="upstream" />
+</Diagram>
+
+The ordering is what makes the pattern useful. By the time the credential is
+attached, `request.user` is populated, so the same request can be authorized
+with [Require User Claims](../policies/require-user-claims-inbound.mdx), rate
+limited per identity, and logged with the caller's subject — and the credential
+the upstream receives is one the caller never held.
+
+That changes what a leaked caller credential is worth. A revoked gateway API key
+takes its holder's access with it, and the upstream secret exists in one place
+instead of one place per caller. It does not change what a caller with
+legitimate access can do. Deciding whether a call _should_ happen is
+authorization, rate limiting, and logging — separate policies, on the same
+request.
+
+## Why every credential policy ends in `-inbound`
+
+Zuplo's pipeline has exactly two policy stages.
+[Inbound policies](../articles/policies.mdx) run before the handler sends the
+request upstream. Outbound policies run on the response, on its way back to the
+caller.
+
+Attaching an upstream credential happens before the request leaves, so every
+credential-injection policy is an inbound policy and carries the `-inbound`
+suffix — including the ones whose entire purpose is the outbound call, like
+`upstream-gcp-service-auth-inbound`. The suffix names the pipeline stage, not
+the direction of the credential. It is not a typo.
+
+The `-outbound` policies work on responses. That is where
+[Secret Masking](../policies/secret-masking-outbound.mdx) belongs: it redacts
+credentials that leaked into a response body before the caller — or an LLM
+reading the response — ever sees them.
+
+## Choosing a policy
+
+| The upstream expects                                                 | Policy                                                                                             | Availability      | Pick it when                                                                                                                                                                                  |
+| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A static key or token in one header                                  | [`set-upstream-api-key-inbound`](../policies/set-upstream-api-key-inbound.mdx)                     | All plans         | One secret, one header. The common case, and the default header is `Authorization`.                                                                                                           |
+| Several headers, or a value composed from more than one variable     | [`set-headers-inbound`](../policies/set-headers-inbound.mdx)                                       | All plans         | The upstream wants a non-standard header name, two headers, or a key plus a tenant identifier.                                                                                                |
+| A GCP ID token or a scoped Google access token, from a stored SA key | [`upstream-gcp-service-auth-inbound`](../policies/upstream-gcp-service-auth-inbound.mdx)           | Enterprise        | Cloud Run, Cloud Functions, or GKE behind IAP (`audience`), or a Google API that needs OAuth `scopes`.                                                                                        |
+| A GCP ID token, with no service-account key stored anywhere          | [`upstream-gcp-federated-auth-inbound`](../policies/upstream-gcp-federated-auth-inbound.mdx)       | Enterprise        | The same IAM-protected services, using Workload Identity Federation instead of a stored key. Audience-bound ID tokens only.                                                                   |
+| A self-signed JWT accepted by Cloud Endpoints or ESPv2               | [`upstream-gcp-jwt-inbound`](../policies/upstream-gcp-jwt-inbound.mdx)                             | Enterprise        | Rarely. The policy's own page steers you to GCP service auth in most cases.                                                                                                                   |
+| An access token from any OAuth 2.0 client-credentials endpoint       | `upstream-oauth-client-credentials-inbound`                                                        | All plans         | An internal authorization server, or any SaaS vendor that issues client-credentials tokens. Set `tokenUrl`, `clientId`, `clientSecret`, and `scope` or `audience` if the provider needs them. |
+| An Entra ID (Azure AD) access token from the client-credentials flow | [`upstream-azure-ad-service-auth-inbound`](../policies/upstream-azure-ad-service-auth-inbound.mdx) | Enterprise        | Azure App Service, Azure Functions, or any Entra-protected resource. It builds the Entra token URL for you from a tenant id.                                                                  |
+| A SigV4-signed request, credentials from a stored IAM key pair       | [`upstream-aws-service-auth-inbound`](../policies/upstream-aws-service-auth-inbound.mdx)           | Enterprise · Beta | Lambda or another AWS service, optionally through an STS AssumeRole. Read [AWS is different](#aws-is-different) first.                                                                        |
+| A SigV4-signed request, with no AWS keys stored anywhere             | [`upstream-aws-federated-auth-inbound`](../policies/upstream-aws-federated-auth-inbound.mdx)       | Enterprise · Beta | The same, using `AssumeRoleWithWebIdentity` instead of a stored key pair.                                                                                                                     |
+| A Firebase admin token                                               | [`upstream-firebase-admin-auth-inbound`](../policies/upstream-firebase-admin-auth-inbound.mdx)     | All plans         | Firestore or another Firebase service called with service-account permissions.                                                                                                                |
+| A Firebase token scoped to one end user                              | [`upstream-firebase-user-auth-inbound`](../policies/upstream-firebase-user-auth-inbound.mdx)       | All plans         | Firebase should apply that user's own permissions. `userId` can be read from `request.user`.                                                                                                  |
+| A JWT proving the call came from your gateway                        | [`upstream-zuplo-jwt-auth-inbound`](../policies/upstream-zuplo-jwt-auth-inbound.mdx)               | Enterprise        | Your own upstream, with no third-party identity provider in the picture. Claims can be copied from the caller.                                                                                |
+| Anything else                                                        | [`custom-code-inbound`](../policies/custom-code-inbound.mdx)                                       | All plans         | Query-string keys, HMAC signatures, or picking the credential from the caller's identity.                                                                                                     |
+
+:::info{title="Enterprise policies are free to try in development"}
+
+The GCP, Azure AD, AWS, and Zuplo-JWT upstream policies above are Enterprise
+features for production traffic, and free to use on any plan for development.
+The two AWS policies are also in beta and may change in non-backward-compatible
+ways. The same applies to two policies this pattern often pairs with:
+[`audit-log-inbound`](../policies/audit-log-inbound.mdx) and
+[`complex-rate-limit-inbound`](../policies/complex-rate-limit-inbound.mdx) are
+Enterprise, while [`rate-limit-inbound`](../policies/rate-limit-inbound.mdx) and
+[`quota-inbound`](../policies/quota-inbound.mdx) are not.
+
+:::
+
+Two policies in the catalog look like they belong in the table and don't.
+`set-headers-outbound` sets headers on the **response**, so it can't
+authenticate an upstream call. `custom-code-outbound` runs after the response
+arrives — useful for reshaping a body, not for signing a request.
+
+### AWS is different
+
+The two AWS policies do not set an `Authorization` header. SigV4 signs the exact
+final request — method, path, query, headers, body hash — so a header computed
+earlier in the pipeline would be wrong by the time the request left.
+
+Instead, both policies resolve AWS credentials and register them on the request
+context. Something later in the pipeline signs with them:
+
+- The [AWS Lambda handler](../handlers/aws-lambda.mdx), which does it for you.
+- Your own code, via `AwsClient.fromContext(context)` in a
+  [custom code policy](../policies/custom-code-inbound.mdx) or
+  [custom handler](../handlers/custom-handler.mdx).
+
+If a route uses one of these policies and the upstream returns 403, check that
+something is actually consuming the resolved credentials. The policy alone does
+not change the outgoing request.
+
+### MCP routes
+
+MCP routes have their own credential broker.
+[`mcp-token-exchange-inbound`](../policies/mcp-token-exchange-inbound.mdx)
+resolves gateway-managed upstream credentials in three modes: `user-oauth`
+(per-user OAuth federation, tokens stored encrypted at rest and keyed to the
+user's subject), `shared-oauth` (one gateway-wide grant an administrator
+connects once), and `id-jag` (Cross-App Access token exchange, built on an
+active IETF draft rather than a finalized RFC). Per-user upstream API keys are
+not part of this set.
+
+See
+[Per-user OAuth to upstream MCP servers](../mcp-gateway/auth/upstream-oauth.mdx)
+for how the outbound surface works, and
+[Connect an upstream that uses an API key](../mcp-gateway/how-to/connect-upstream-api-key.mdx)
+for upstreams with no OAuth at all.
+
+## Where the credential lives
+
+Upstream secrets belong in
+[environment variables](../articles/environment-variables.mdx), referenced from
+policy configuration with `$env(VAR_NAME)` and from code with
+`environment.VAR_NAME`. Values are encrypted at rest; values marked as secrets
+are write-only, so they can't be read back after they're set.
+
+Two behaviors surprise people:
+
+- **A changed value needs a new deployment.** Variables are applied to an
+  environment at deploy time. Updating a credential without redeploying leaves
+  the old value in service.
+- **The CLI and the Developer API set variables per branch.**
+  [`zuplo variable create`](../cli/variable-create.mdx) and
+  [`zuplo variable update`](../cli/variable-update.mdx) both take a `--branch`
+  flag and create a record for that branch alone.
+
+:::caution{title="Set shared credentials in the Portal, not the CLI"}
+
+There is no all-environments assignment in the CLI or the Developer API. Only
+the
+[environment-variable editor](../articles/environment-variables.mdx#environment-variable-editor)
+in the Zuplo Portal can apply one variable to several environments at once —
+open **Settings → Environment Variables** in your project and select every
+environment the credential belongs to.
+
+A credential seeded per branch looks correct in the environment where it was
+created and is simply absent everywhere else. Nothing fails at build or deploy
+time; the first sign of trouble is a 401 or 403 from the upstream on live
+traffic, which can go unnoticed for days on a low-volume route.
+
+:::
+
+The strongest option is to store nothing. Both federated policies
+([GCP](../policies/upstream-gcp-federated-auth-inbound.mdx),
+[AWS](../policies/upstream-aws-federated-auth-inbound.mdx)) exchange the
+gateway's own OIDC identity for short-lived cloud credentials, so there is no
+long-lived key to leak, rotate, or seed into an environment.
+
+## Related
+
+- [Securing your backend](../articles/securing-your-backend.mdx) — the six ways
+  to make sure only your gateway can reach your origin.
+- [Secure a GCP backend with Zuplo upstream auth](../articles/gke-with-upstream-auth-policy.mdx)
+  — an end-to-end walkthrough with GKE and Identity-Aware Proxy.
+- [Authentication](./authentication.mdx) — the inbound half of the request.
+- [Environment variables](../articles/environment-variables.mdx) — syntax,
+  environments, and deployment behavior.
+- [Policies](../articles/policies.mdx) — how the inbound and outbound stages fit
+  together.

package/package.json

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