zuplo 6.73.26 → 6.73.28

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

@@ -16,8 +16,11 @@ npx create-zuplo-api@latest
 `create-zuplo-api` comes with the following options:
 
 - `-v, --version` - Output the current version of create-zuplo-api
-- `--eslint` - Initialize with ESLint configuration
-- `--prettier` - Initialize with Prettier configuration
+- `--linter <linter>` - The linter to configure (`eslint`, `biome`, `oxlint`, or
+  `none`). See
+  [Choosing a linter and formatter](#choosing-a-linter-and-formatter)
+- `--formatter <formatter>` - The formatter to configure (`prettier`, `biome`,
+  `oxfmt`, or `none`)
 - `--empty` - Initialize an empty project
 - `--use-npm` - Explicitly tell the CLI to bootstrap the application using npm
 - `--use-pnpm` - Explicitly tell the CLI to bootstrap the application using pnpm
@@ -28,7 +31,19 @@ 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)
+- `--template <template-name>` - A built-in template to bootstrap the API with
+  (`default`, `default-empty`, or `ai-gateway-v2`). Can't be combined with
+  `--example` or `--empty`. See [Choosing a template](#choosing-a-template)
 - `-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 +53,222 @@ 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-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, or an explicit
+value such as `--linter none`, 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 --linter none --formatter none --no-install --no-git
+```
+
+If you pass both spellings of the same option, the affirmative flag wins — so
+`--git --no-git` initializes a git repository. `--no-server-project` is the
+exception: it always wins, even when combined with `--server-project` or
+`--account`.
+
+### Choosing a template
+
+`--template` selects which built-in template the CLI scaffolds from. Without the
+flag you get the `default` template.
+
+| Value           | What it scaffolds                                                                             |
+| --------------- | --------------------------------------------------------------------------------------------- |
+| `default`       | Sample `/todos` routes, a `hello-world` module, a dev portal in `docs/`, and VS Code settings |
+| `default-empty` | The same project with no routes defined and no VS Code settings                               |
+| `ai-gateway-v2` | An [AI Gateway](../ai-gateway/introduction.mdx) project, without a dev portal                 |
+
+`--empty` is shorthand for `--template default-empty`.
+
+The `ai-gateway-v2` template scaffolds `config/ai.oas.json`, which routes
+`/:app_id/v1/*` to the AI Gateway handler, and `config/policies.json`, which
+declares the policies an application's policy chain can select. It ships no
+`docs/` directory, so the CLI skips the
+[dev portal](../dev-portal/introduction.mdx) workspace:
+
+```bash
+npx create-zuplo-api@latest my-gateway --template ai-gateway-v2
+```
+
+`--template` names a built-in template, which is why it can't be combined with
+`--example` (a project pulled from GitHub) or with `--empty` (use
+`--template default-empty`). Either combination stops the CLI before it writes
+any files, as does a template name that isn't in the table above.
+
+### Choosing a linter and formatter
+
+`--linter` and `--formatter` pick the tools the CLI sets up. Without either flag
+the CLI asks, with ESLint and Prettier preselected.
+
+| `--linter` | Config file        | Dev dependencies                            |
+| ---------- | ------------------ | ------------------------------------------- |
+| `eslint`   | `eslint.config.js` | `eslint`, `@eslint/js`, `typescript-eslint` |
+| `biome`    | `biome.json`       | `@biomejs/biome`                            |
+| `oxlint`   | `.oxlintrc.json`   | `oxlint`                                    |
+| `none`     | None               | None                                        |
+
+| `--formatter`     | Config file        | Dev dependencies |
+| ----------------- | ------------------ | ---------------- |
+| `prettier`        | `.prettierrc.json` | `prettier`       |
+| `biome`           | `biome.json`       | `@biomejs/biome` |
+| `oxfmt` (in beta) | `.oxfmtrc.json`    | `oxfmt`          |
+| `none`            | None               | None             |
+
+A linter adds `lint` and `lint:fix` scripts to `package.json`, and a formatter
+adds `format` and `format:check`. The dev portal workspace in `docs/` gets the
+same `lint` script. The CLI also writes a `.vscode/extensions.json` that
+recommends the editor extensions for the tools you picked.
+
+Biome fills both roles from one dependency and a single `biome.json`:
+
+```bash
+npx create-zuplo-api@latest my-api --linter biome --formatter biome
+```
+
+Picking Biome as the linter preselects it as the formatter in the interactive
+prompt. Pairing ESLint with Prettier also installs `eslint-config-prettier`, so
+the linter doesn't fight the formatter.
+
+An unrecognized value is an error and prints the valid values. With `--yes` or in
+CI, the CLI uses your saved preferences, or ESLint and Prettier if you have none.
+
+### 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
+```
+
+The CLI asks the following questions:
+
+```text
+? What is your project named? › my-api
+? Create a matching project on portal.zuplo.com? › No / Yes
+? Which linter would you like to use? › - Use arrow-keys. Return to submit.
+❯   ESLint
+    Biome
+    Oxlint
+    None
+? Which formatter would you like to use? › - Use arrow-keys. Return to submit.
+❯   Prettier
+    Biome
+    Oxfmt
+    None
+? Which AI coding agents would you like to configure? › - Space to select. Return to submit
+◯   Claude Code
+◯   GitHub Copilot
+◯   Cursor
+◯   Windsurf
+◯   OpenAI Codex
+◯   None
 ```
 
-You will then be asked the following prompts:
+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 +280,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/docs/policies/_index.md

@@ -101,6 +101,7 @@
 | upstream-gcp-federated-auth-inbound | Upstream GCP Federated Auth | Authenticates with GCP resources or Google services using Workload Identity Federation allowing secure access to these resources without requiring the use of a service account private key. | api-gateway |
 | upstream-gcp-jwt-inbound | Upstream GCP Self-Signed JWT | Creates a self-signed JWT token (generated using a Google Service Account JSON) and attaches it to the outgoing request. Useful when calling GCP services like Cloud Endpoints / ESPv2 | api-gateway |
 | upstream-gcp-service-auth-inbound | Upstream GCP Service Auth | Creates an ID Token from Google's OAuth service and attaches it to the outgoing request. Useful when calling GCP services or Google APIs that are secured with GCP IAM. | api-gateway |
+| upstream-oauth-client-credentials-inbound | Upstream OAuth 2.0 Client Credentials Auth | Fetches an access token from any OAuth 2.0 token endpoint using the client credentials grant and adds it to a header (`Authorization` by default) on the upstream request. Tokens are cached until shortly before they expire. | api-gateway |
 | upstream-zuplo-jwt-auth-inbound | Upstream Zuplo JWT | Generates a Zuplo JWT token and attaches it to the outgoing request. This policy creates a self-signed JWT using the Zuplo JWT plugin and adds it to the specified header for upstream authentication. | api-gateway |
 | web-bot-auth-inbound | Web Bot Auth | Authenticate bots using web-bot-auth HTTP Message Signatures. | api-gateway |
 | xml-to-json-outbound | XML to JSON | Parses XML and converts it to JSON. | api-gateway |

package/docs/policies/upstream-oauth-client-credentials-inbound/doc.md

@@ -0,0 +1,124 @@
+This policy authenticates your Zuplo gateway to OAuth 2.0-protected backend
+services by automatically adding an access token to the `Authorization` header
+(or a custom header) of upstream requests. It uses the OAuth 2.0 client
+credentials grant against any token endpoint you configure, so it works with
+Auth0, Okta, Keycloak, Microsoft Entra ID, and any other standards-compliant
+identity provider.
+
+### How It Works
+
+The policy performs the following operations:
+
+1. Requests an access token from the configured token endpoint using the client
+   credentials grant
+2. Caches the token for subsequent requests until it nears expiration
+3. Adds the token to the configured header (default `Authorization`) using the
+   `token_type` returned by the token endpoint, falling back to the configured
+   `headerScheme` (default `Bearer`)
+4. Automatically handles token renewal when needed
+
+Tokens are cached for `expires_in - expirationOffsetSeconds` seconds. If the
+token endpoint doesn't return an `expires_in` value, the policy caches the token
+conservatively as if it expired after 10 minutes (5 minutes with the default
+`expirationOffsetSeconds` of 300) rather than caching it indefinitely.
+
+### Policy Configuration
+
+Configure the policy with your identity provider's token endpoint and client
+credentials:
+
+```json
+{
+  "name": "upstream-oauth-client-credentials",
+  "export": "UpstreamOAuthClientCredentialsInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "tokenUrl": "https://your-tenant.us.auth0.com/oauth/token",
+    "clientId": "$env(OAUTH_CLIENT_ID)",
+    "clientSecret": "$env(OAUTH_CLIENT_SECRET)",
+    "audience": "https://api.example.com",
+    "scope": "read:orders write:orders"
+  }
+}
+```
+
+### Sending Client Credentials
+
+By default (`credentialsIn: "body"`), the client credentials are sent as
+`client_id` and `client_secret` form parameters in the token request body. While
+[RFC 6749 section 2.3.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1)
+recommends HTTP Basic authentication, `body` is the default because it's the
+method most widely accepted across identity providers (including Auth0, Okta,
+Entra ID, and Keycloak) and avoids credential-encoding differences between
+providers' Basic authentication implementations.
+
+Set `credentialsIn` to `header` to send the credentials with HTTP Basic
+authentication instead:
+
+```json
+{
+  "options": {
+    "tokenUrl": "https://idp.example.com/oauth2/token",
+    "clientId": "$env(OAUTH_CLIENT_ID)",
+    "clientSecret": "$env(OAUTH_CLIENT_SECRET)",
+    "credentialsIn": "header"
+  }
+}
+```
+
+### Provider-Specific Parameters
+
+Some identity providers require extra form parameters on the token request. Use
+`additionalParameters` to send them, for example the `resource` parameter:
+
+```json
+{
+  "options": {
+    "tokenUrl": "https://idp.example.com/oauth2/token",
+    "clientId": "$env(OAUTH_CLIENT_ID)",
+    "clientSecret": "$env(OAUTH_CLIENT_SECRET)",
+    "additionalParameters": {
+      "resource": "https://api.example.com"
+    }
+  }
+}
+```
+
+The `grant_type` parameter is always `client_credentials` and the dedicated
+`clientId`, `clientSecret`, `scope`, and `audience` options always take
+precedence over entries in `additionalParameters`.
+
+### Usage Example
+
+Apply the policy to routes that need to call your OAuth-protected backend:
+
+```json
+{
+  "paths": {
+    "/api/orders": {
+      "get": {
+        "x-zuplo-route": {
+          "policies": {
+            "inbound": ["jwt-auth", "upstream-oauth-client-credentials"]
+          },
+          "handler": {
+            "export": "forwardToOrigin",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "baseUrl": "https://api.internal.example.com"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Security Considerations
+
+- Store the client secret as an environment variable using `$env(VARIABLE_NAME)`
+  syntax
+- Grant the OAuth client the minimum scopes required to access your backend
+  services
+- Regularly rotate your client secrets according to your security policies

package/docs/policies/upstream-oauth-client-credentials-inbound/intro.md

@@ -0,0 +1,18 @@
+Secure your origin server with OAuth 2.0 authentication by automatically adding
+an `Authorization` header to upstream requests. This policy enables your Zuplo
+gateway to authenticate with any OAuth 2.0 identity provider that supports the
+client credentials grant — such as Auth0, Okta, Keycloak, Microsoft Entra ID, or
+your own authorization server.
+
+With this policy, you'll benefit from:
+
+- **Enhanced Backend Security**: Restrict access to your origin servers to only
+  your Zuplo gateway
+- **Simplified Authentication**: Delegate authentication and authorization to
+  your gateway without backend code changes
+- **Automatic Token Management**: Handle token acquisition, caching, and renewal
+  automatically
+- **Provider Flexibility**: Works with any standards-compliant OAuth 2.0 token
+  endpoint, no provider-specific policy required
+- **Credential Security**: Store sensitive client credentials securely in your
+  Zuplo environment

package/docs/policies/upstream-oauth-client-credentials-inbound/schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/upstream-oauth-client-credentials-inbound.json",
+  "type": "object",
+  "title": "Upstream OAuth 2.0 Client Credentials Auth",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "requiresAI": false,
+  "products": ["api-gateway"],
+  "description": "Fetches an access token from any OAuth 2.0 token endpoint using the client credentials grant and adds it to a header (`Authorization` by default) on the upstream request. Tokens are cached until shortly before they expire.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "UpstreamOAuthClientCredentialsInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "UpstreamOAuthClientCredentialsInboundPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": ["tokenUrl", "clientId", "clientSecret"],
+          "properties": {
+            "tokenUrl": {
+              "type": "string",
+              "examples": ["https://your-tenant.us.auth0.com/oauth/token"],
+              "description": "The URL of the OAuth 2.0 token endpoint that issues the access token."
+            },
+            "clientId": {
+              "type": "string",
+              "examples": ["my-client-id"],
+              "description": "The client ID used to authenticate with the token endpoint."
+            },
+            "clientSecret": {
+              "type": "string",
+              "examples": ["$env(OAUTH_CLIENT_SECRET)"],
+              "description": "The client secret used to authenticate with the token endpoint."
+            },
+            "scope": {
+              "type": "string",
+              "examples": ["read:orders write:orders"],
+              "description": "Space-delimited list of scopes to request. When not set, the `scope` parameter is omitted from the token request."
+            },
+            "audience": {
+              "type": "string",
+              "examples": ["https://api.example.com"],
+              "description": "The value of the `audience` form parameter sent to the token endpoint. Required by some identity providers such as Auth0. When not set, the parameter is omitted from the token request."
+            },
+            "credentialsIn": {
+              "type": "string",
+              "title": "OAuthClientCredentialsLocation",
+              "default": "body",
+              "enum": ["body", "header"],
+              "x-advanced": true,
+              "description": "Where the client credentials are sent on the token request. `body` sends `client_id` and `client_secret` as form parameters. `header` sends them with HTTP Basic authentication as described in RFC 6749 section 2.3.1."
+            },
+            "additionalParameters": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "x-advanced": true,
+              "description": "Additional form parameters to include in the token request, for example `resource` for identity providers that require it."
+            },
+            "headerName": {
+              "type": "string",
+              "default": "Authorization",
+              "x-advanced": true,
+              "description": "The name of the header on the upstream request that the access token is set on."
+            },
+            "headerScheme": {
+              "type": "string",
+              "default": "Bearer",
+              "x-advanced": true,
+              "description": "The scheme that prefixes the access token in the header. When the token response includes a `token_type`, that value is used instead."
+            },
+            "tokenRetries": {
+              "type": "number",
+              "default": 3,
+              "x-advanced": true,
+              "description": "The number of times to retry fetching the token in the event of a failure."
+            },
+            "expirationOffsetSeconds": {
+              "type": "number",
+              "default": 300,
+              "x-advanced": true,
+              "description": "The number of seconds less than the token expiration to cache the token."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "UpstreamOAuthClientCredentialsInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "audience": "https://api.example.com",
+            "clientId": "my-client-id",
+            "clientSecret": "$env(OAUTH_CLIENT_SECRET)",
+            "credentialsIn": "body",
+            "expirationOffsetSeconds": 300,
+            "headerName": "Authorization",
+            "headerScheme": "Bearer",
+            "scope": "read:orders write:orders",
+            "tokenRetries": 3,
+            "tokenUrl": "https://your-tenant.us.auth0.com/oauth/token"
+          }
+        }
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.73.26",
+  "version": "6.73.28",
   "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.28",
+    "@zuplo/core": "6.73.28",
+    "@zuplo/runtime": "6.73.28",
     "@zuplo/test": "1.4.0"
   }
 }