zuplo 6.72.2 → 6.72.7

package/docs/articles/{custom-audit-log-policy.mdx → custom-audit-logs.mdx}

@@ -1,29 +1,22 @@
 ---
-title: Custom Audit Logging Policy
-sidebar_label: Audit Logging
+title: Custom Audit Logs
+sidebar_label: Custom Audit Logs
 ---
 
-This guide explains how to add custom audit logging beyond the scope of the
-`AuditLogsInboundPolicy`.
+[Zuplo Audit Logs](./audit-logs.mdx) stores your audit trail in Zuplo and gives
+you a portal viewer and query API out of the box. If your organization uses an
+external audit logging service instead, you can send events to it directly from
+the gateway with a [custom policy](../policies/custom-code-inbound.mdx) that
+uses [runtime hooks](../programmable-api/runtime-extensions.mdx). This approach
+works on any plan — it's just custom code — and gives you full control over
+which events are recorded, the event format, and the destination.
 
-Audit logging is an important part of API security that plays a critical role in
-detecting and correcting issues such as unauthorized access or permission
-elevations within your system. Audit logging is also a requirement for many
-compliance certifications as well as part of the buying criteria for larger
-enterprises.
-
-Adding Audit Logging to your APIs that are secured with Zuplo is as easy as
-adding a custom policy. Typically you want to add audit logs to any API that
-modifies data, however depending on the API you may want it on read operations
-as well (for example retrieve a secret key, etc.)
-
-## Example Policy: WorkOS Audit Logs
+## Example: WorkOS Audit Logs
 
 [WorkOS](https://workos.com/) provides various services that help enable
-enterprise features on your service such as SSO and Audit Logs. With Zuplo it's
-easy to create a [custom policy](../policies/custom-code-inbound.mdx) that uses
-[runtime hooks](../programmable-api/runtime-extensions.mdx) to log API calls
-using their API.
+enterprise features on your service such as SSO and Audit Logs. The following
+custom policy logs API calls to the WorkOS Audit Logs API after each response is
+sent:
 
 ```ts
 import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
@@ -34,7 +27,7 @@ export async function auditLogPlugin(
   policyName: string,
 ) {
   // Clone the request so the body can be read in the hook
-  // note: remove this is you don't need content from the body
+  // note: remove this if you don't need content from the body
   const cloned = request.clone();
   context.addResponseSendingFinalHook(async (response) => {
     const incomingBody = await cloned.json();
@@ -48,7 +41,7 @@ export async function auditLogPlugin(
         version: 1,
         actor: {
           type: "user",
-          // Add the use the user sub for authenticated users
+          // Use the user sub for authenticated users
           id: request.user.sub,
           metadata: {
             role: "user",
@@ -93,3 +86,14 @@ export async function auditLogPlugin(
   return request;
 }
 ```
+
+The same pattern works for any provider with an HTTP API — swap the event shape
+and endpoint for your provider's, and store credentials in
+[environment variables](./environment-variables.mdx).
+
+## Related resources
+
+- [Audit logging overview](./audit-logging.mdx) — why audit logging matters and
+  how the options compare
+- [Zuplo Audit Logs](./audit-logs.mdx) — the built-in feature with portal
+  viewing and a query API

package/docs/articles/graphql-security.mdx

@@ -180,7 +180,8 @@ outbound filter policy goes in the `outbound` array:
 ## Example repository
 
 For a complete, runnable setup, see the
-[GraphQL API with Zuplo example repository](https://github.com/zuplo/zuplo-graphql-example).
+[GraphQL API with Zuplo example repository](https://github.com/zuplo-samples/graphql).
+You can [deploy it to your own account in one click](./graphql.mdx).
 
 ## Next steps
 

package/docs/articles/graphql.mdx

@@ -12,6 +12,14 @@ Zuplo has rich support for GraphQL. Pass your requests through the gateway,
 attach policies, track operations with analytics, and publish documentation for
 your schema in the Dev Portal. This guide walks you through setting it up.
 
+<ZupIt repoUrl="https://github.com/zuplo-samples/graphql">
+
+Want to see it working first? This example proxies a public GraphQL API with
+edge caching, query depth limiting, and analytics already wired up — deploy it
+to your own Zuplo account in one click.
+
+</ZupIt>
+
 :::tip{title="TL;DR"}
 
 - [ ] Proxy your GraphQL endpoint through a POST `/graphql` route with the URL

package/docs/articles/opentelemetry.mdx

@@ -7,10 +7,9 @@ Zuplo ships with an OpenTelemetry plugin (`@zuplo/otel`) that instruments your
 API and exports traces and logs in OpenTelemetry format. The quickest way to use
 it is Zuplo's built-in tracing: add the plugin and your traces are stored by
 Zuplo and shown in the portal's **Observability** tab, with no collector to run
-or backend to host. You can also export to your own OpenTelemetry backend, or to
-both at once.
-
-<EnterpriseFeature name="OpenTelemetry" />
+or backend to host. Built-in tracing is available on every plan. You can also
+export to your own OpenTelemetry backend (an Enterprise feature), or to both at
+once.
 
 ## Tracing
 
@@ -68,7 +67,8 @@ Deploy your project and open the **Observability** tab to see traces.
 Each trace is tagged with the account, project, deployment, and environment it
 ran in, plus the request ID (the `zp-rid` value) that also appears on your
 [logs](#logging), so you can move between a request's logs and its trace. How
-long traces are kept depends on your plan.
+long traces are kept depends on your plan — see
+[data retention](../analytics/access-and-entitlements.md#data-retention).
 
 :::note
 
@@ -81,6 +81,8 @@ still run.
 
 ### Export to Your Own Backend
 
+<EnterpriseFeature name="Exporting to your own OpenTelemetry backend" />
+
 To send traces to an OpenTelemetry service such as
 [Honeycomb](https://honeycomb.io), [Middleware](https://middleware.io/),
 [Dynatrace](https://dynatrace.com), [Jaeger](https://www.jaegertracing.io/), or

package/docs/articles/securing-backend-mtls.mdx

@@ -30,11 +30,38 @@ gateways, and Zuplo can verify it's connecting to the correct backend service.
 
 Before you begin, you need:
 
-- A client certificate and private key generated from a Certificate Authority
-  (CA) that your backend trusts
+- A PEM-encoded client certificate and matching private key generated from a
+  Certificate Authority (CA) that your backend trusts
 - Your backend service configured to require and validate client certificates
 - The Zuplo CLI installed (see [CLI documentation](../cli/overview.mdx))
 
+## Client certificate requirements
+
+The certificate uploaded to Zuplo is the client, or leaf, certificate that the
+gateway presents to your backend. It should have the following properties:
+
+- X.509 version 3
+- `Basic Constraints: critical, CA:FALSE`
+- `Key Usage: critical, Digital Signature`
+- `Extended Key Usage: TLS Web Client Authentication` (`clientAuth`)
+- An RSA key between 2048 and 8192 bits, or an ECDSA key using P-256, P-384, or
+  P-521
+- A SHA-256 or stronger signature
+- A subject that uniquely identifies the gateway credential
+- A validity period appropriate for your certificate rotation policy
+
+The issuing CA certificate must be X.509 version 3 with
+`Basic Constraints: critical, CA:TRUE` and a key usage that includes
+`Certificate Sign` and `CRL Sign`. Your backend's trust store must contain the
+CA certificates needed to build a path from the client certificate to a trusted
+root. When the trusted CA directly signs the client certificate, you do not need
+a client certificate-chain bundle. If an intermediate CA signs it, follow your
+backend's requirements for presenting and trusting the intermediate chain.
+
+The private key must match the public key in the client certificate. Keep it
+secret and limit access to it. The key must be unencrypted when uploaded to
+Zuplo so the gateway can use it without a passphrase.
+
 ## 1/ Upload Your Certificate
 
 Use the Zuplo CLI to upload your client certificate and private key to your
@@ -229,10 +256,72 @@ For local development, consider:
 
 ### Certificate Validation Errors
 
-If your backend rejects the certificate, verify:
+Inspect the certificate and confirm its subject, issuer, validity, and client
+authentication purpose:
+
+```bash
+openssl x509 \
+  -in client.crt \
+  -noout \
+  -subject \
+  -issuer \
+  -serial \
+  -dates \
+  -purpose
+```
+
+`SSL client` should report `Yes`. To inspect all extensions, run
+`openssl x509 -in client.crt -noout -text` and confirm the certificate reports
+`CA:FALSE`, `Digital Signature`, and `TLS Web Client Authentication`.
+
+Check that the certificate will remain valid for at least seven days:
+
+```bash
+openssl x509 -in client.crt -noout -checkend 604800
+```
+
+Validate the certificate path against the same CA bundle your backend trusts:
+
+```bash
+openssl verify \
+  -verbose \
+  -purpose sslclient \
+  -x509_strict \
+  -show_chain \
+  -CAfile backend-client-ca-bundle.pem \
+  client.crt
+```
+
+The expected result is `client.crt: OK`. Common errors include:
+
+- `unable to get local issuer certificate`: The issuing CA or an intermediate CA
+  is missing from the backend's trust bundle.
+- `unsupported certificate purpose`: The client certificate is missing the
+  `clientAuth` extended key usage.
+- `certificate has expired`: The client certificate is outside its validity
+  period.
+- `invalid CA certificate`: An issuing certificate is missing valid CA
+  extensions.
+- `key usage does not include certificate signing`: An issuing CA does not have
+  the `keyCertSign` key usage.
+
+Confirm that the certificate and private key contain the same public key:
+
+```bash
+CERT_KEY_HASH=$(openssl x509 -in client.crt -noout -pubkey | openssl sha256)
+PRIVATE_KEY_HASH=$(openssl pkey -in client.key -pubout | openssl sha256)
+
+test "$CERT_KEY_HASH" = "$PRIVATE_KEY_HASH" &&
+  echo "Certificate and private key match" ||
+  echo "ERROR: Certificate and private key do not match"
+```
+
+If your backend still rejects the certificate, verify:
 
 - The certificate is signed by a CA that your backend trusts
 - The certificate hasn't expired
+- The certificate has the required key usage and extended key usage
+- The certificate and private key match
 - The certificate name in your code matches the uploaded certificate name
 
 ### Connection Failures

package/docs/articles/troubleshooting-slow-responses.mdx

@@ -240,9 +240,10 @@ For the most detailed view of where time is spent in your request pipeline,
 enable [OpenTelemetry tracing](./opentelemetry.mdx). The OpenTelemetry plugin
 automatically instruments your API and provides span-level timing for each stage
 of the request lifecycle — including inbound policies, the handler, outbound
-policies, and any subrequests made via `fetch` in custom code.
-
-<EnterpriseFeature name="OpenTelemetry" />
+policies, and any subrequests made via `fetch` in custom code. Built-in tracing
+is available on every plan; see
+[data retention](../analytics/access-and-entitlements.md#data-retention) for how
+much trace history you can query.
 
 With tracing enabled, you can see exactly how long each policy and handler takes
 to execute, making it straightforward to identify which component is adding

package/docs/articles/troubleshooting.md

@@ -179,7 +179,9 @@ const response = await fetch("https://api.example.com/data", {
 The Zuplo Portal provides real-time log viewing for deployed environments. Open
 the **Observability** tab in your project — the **Logs** view opens by default —
 then use the **Environment** filter to select the deployed environment and see
-live request logs and any messages logged with `context.log`.
+live request logs and any messages logged with `context.log`. How far back you
+can search depends on your plan — see
+[Access and entitlements](../analytics/access-and-entitlements.md#data-retention).
 
 ### Using context.log
 

package/docs/policies/_index.md

@@ -91,6 +91,7 @@
 | request-size-limit-inbound | Request Size Limit | Enforces a maximum size in bytes of the incoming request. | api-gateway |
 | request-validation-inbound | Request Validation | Validates incoming requests against your OpenAPI specification. Checks query parameters, path parameters, headers, and request body to ensure they match the defined schema before processing. | api-gateway |
 | require-origin-inbound | Require Origin | Sets an allow-list for an origin header | api-gateway |
+| require-user-claims-inbound | Require User Claims | Authorizes requests by validating claims on the authenticated user (`request.user`) against a configurable rule of `and`/`or` combinators and per-claim `eq`, `in`, and `startsWith` checks. Run it after any authentication policy that populates `request.user` — a JWT auth policy, API key auth, mTLS, and so on — to allow only specific callers (service accounts, OAuth clients, tenants, groups) without writing custom code.  Every check fails closed: a missing or non-primitive claim never matches, comparisons are strict and type-sensitive, and requests without an authenticated user receive a 401 response. Denied requests receive a 403 response that does not echo claim values or expected values; the failing checks are written to the request log instead.  Validation of the options runs lazily inside the policy constructor, which the runtime caches per policy name. Misconfigured options therefore fail on first use with a customer-facing `ConfigurationError` instead of failing at module load. | api-gateway |
 | secret-masking-outbound | Secret Masking | Masks common secrets like Zuplo API keys, GitHub tokens, or SSH private key in the response body. | api-gateway |
 | semantic-cache-inbound | Semantic Cache | Respond to matched incoming requests with semantically cached content  The Semantic Cache Inbound policy caches responses based on semantic similarity of cache keys rather than exact matches. This allows for more flexible caching where similar requests can return cached responses even if the cache key is not exactly the same.  The policy uses Large Language Model (LLM) embeddings to determine semantic similarity between cache keys based on a configurable similarity tolerance.  Options: - semanticTolerance: The semantic similarity threshold for semantic cache matches (0-1, default: 0.2). Values closer to 0 require higher similarity. Can be overridden by custom functions. - expirationSecondsTtl: The timeout of the cache in seconds (default: 3600, 1 hour). Can be overridden by custom functions. - namespace: Optional namespace to isolate cache entries (default: "default"). Useful for multi-tenant scenarios or different cache contexts. - cacheBy: Determines how cache keys are generated: 'function' for custom logic or 'propertyPath' to extract from JSON body. | ai-gateway |
 | set-body-inbound | Set Body | Sets the body of the request in the inbound pipeline - make sure to convert a GET/HEAD request to another method when using this policy. | api-gateway |
@@ -103,6 +104,8 @@
 | traffic-splitting-inbound | Traffic Splitting | Splits traffic randomly across a set of weighted base paths. On each request one base path is selected (weighted by `weight`) and written to the request custom context at `customOutputProperty`. Reference it from a later URL Rewrite `rewritePattern` or URL Forward `baseUrl`, e.g. `${context.custom.trafficSplitting.basePath}`. | api-gateway |
 | transform-body-inbound | Transform Request Body | Transform the body of an incoming request. | api-gateway |
 | transform-body-outbound | Transform Response Body | Transform the body of an outgoing response. | api-gateway |
+| upstream-aws-federated-auth-inbound | Upstream AWS Federated Auth | Resolves AWS credentials with STS AssumeRoleWithWebIdentity using Zuplo's ambient OIDC identity — no AWS keys are stored anywhere. The role's trust policy must trust the Zuplo OIDC identity provider. Resolved credentials are registered on the request context for the AWS Lambda handler and custom code to sign upstream requests with `AwsClient.fromContext`. This policy does not itself sign or forward the request. | api-gateway |
+| upstream-aws-service-auth-inbound | Upstream AWS Service Auth | Resolves AWS credentials from static access keys (optionally exchanged for an IAM role's temporary credentials via STS AssumeRole) and registers them on the request context. The AWS Lambda handler and custom code read them with `AwsClient.fromContext` to sign upstream requests. This policy does not itself sign or forward the request. | api-gateway |
 | upstream-azure-ad-service-auth-inbound | Upstream Azure AD Service Auth | Uses Azure Active Directory to add an Authorization header to the request in order to authenticate requests using Azure identity. | api-gateway |
 | upstream-firebase-admin-auth-inbound | Upstream Firebase Admin Auth | Creates a Firebase Admin token and attaches it to the outgoing request. Useful when calling Firebase services as an administrator. | api-gateway |
 | upstream-firebase-user-auth-inbound | Upstream Firebase User Auth | Creates a Firebase custom user token and attaches it to the outgoing request. Useful when calling Firebase services as user. | api-gateway |

package/docs/policies/audit-log-inbound/doc.md

@@ -16,14 +16,14 @@ requests).
 ## Controlling What's Logged
 
 Audit events can contain personal or sensitive data. To keep audit logging
-compliant with your own data-handling and PII policies, use the `include`
-option to turn individual fields off. Everything is captured by default; set a
-flag to `false` to omit it:
+compliant with your own data-handling and PII policies, use the `include` option
+to turn individual fields off. Everything is captured by default; set a flag to
+`false` to omit it:
 
 - `queryParams` — the request's query-string parameters (in the logged URL).
-- `user` — the authenticated user / actor identity (subject, email,
-  connection). The `user` vs `anonymous` classification is always kept, but the
-  identifying values are omitted when disabled.
+- `user` — the authenticated user / actor identity (subject, email, connection).
+  The `user` vs `anonymous` classification is always kept, but the identifying
+  values are omitted when disabled.
 - `ipAddress` — the caller's IP address.
 - `geolocation` — the caller's country, region, and city.
 
@@ -87,7 +87,8 @@ export async function deleteAccount(
 The event object passed to `log()` supports the following fields. Only `type` is
 required.
 
-- `type` — the event type, in reverse-DNS form (e.g. `com.acme.account.deleted`).
+- `type` — the event type, in reverse-DNS form (e.g.
+  `com.acme.account.deleted`).
 - `subject` — the primary entity the event is about.
 - `resources` — an array of `{ type, id, metadata? }` describing the resources
   the event affected.
@@ -95,9 +96,8 @@ required.
 - `data` — any additional structured data to attach to the event.
 - `actor` — override the automatically-derived actor
   (`{ sub, type, email, connection }`).
-- `country`, `region`, `city` — override the caller's geolocation. These
-  default to the current request's location, so you normally don't need to set
-  them.
+- `country`, `region`, `city` — override the caller's geolocation. These default
+  to the current request's location, so you normally don't need to set them.
 
 Audit logging is best-effort: `log()` never throws and never blocks or fails the
 request, even if an event cannot be recorded.
@@ -134,4 +134,9 @@ pass, and the remaining fields are populated from the request context.
 
 ## Viewing Audit Logs
 
-In-portal viewing and retrieval of audit logs is coming soon.
+Audit logs are available in the [Zuplo portal](https://portal.zuplo.com) under
+your project's Audit Log service, where you can browse and search the events
+recorded by this policy.
+
+You can also query audit logs programmatically using the
+[Zuplo API](https://zuplo.com/docs/api).

package/docs/policies/authzen-inbound/schema.json

@@ -7,7 +7,7 @@
   "isPaidAddOn": false,
   "isEnterprise": true,
   "isInternal": false,
-  "isBeta": true,
+  "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
   "products": ["api-gateway"],

package/docs/policies/axiomatics-authz-inbound/schema.json

@@ -7,7 +7,7 @@
   "isPaidAddOn": false,
   "isEnterprise": true,
   "isInternal": false,
-  "isBeta": true,
+  "isBeta": false,
   "isHidden": false,
   "requiresAI": false,
   "products": ["api-gateway"],

package/docs/policies/clerk-jwt-auth-inbound/schema.json

@@ -42,8 +42,8 @@
             },
             "frontendApiUrl": {
               "type": "string",
-              "examples": ["https://sensible-skunk-49.clerk.accounts.dev"],
-              "description": "Your Clerk frontend api url, i.e. `https://sensible-skunk-49.clerk.accounts.dev`. Can be found in the Clerk portal: https://dashboard.clerk.com/last-active?path=api-keys."
+              "examples": ["https://verb-noun-00.clerk.accounts.dev"],
+              "description": "Your Clerk Frontend API URL, i.e. `https://verb-noun-00.clerk.accounts.dev`. Can be found in the Clerk portal: https://dashboard.clerk.com/last-active?path=api-keys."
             },
             "oAuthResourceMetadataEnabled": {
               "type": "boolean",
@@ -59,7 +59,7 @@
           "module": "$import(@zuplo/runtime)",
           "options": {
             "allowUnauthenticatedRequests": false,
-            "frontendApiUrl": "https://sensible-skunk-49.clerk.accounts.dev",
+            "frontendApiUrl": "https://verb-noun-00.clerk.accounts.dev",
             "oAuthResourceMetadataEnabled": false
           }
         }

package/docs/policies/mcp-auth0-oauth-inbound/schema.json

@@ -100,7 +100,7 @@
                 {
                   "type": "object",
                   "additionalProperties": false,
-                  "required": ["enabled", "trustedIssuers"],
+                  "required": ["enabled"],
                   "properties": {
                     "enabled": {
                       "const": true,
@@ -109,21 +109,24 @@
                     "trustedIssuers": {
                       "type": "array",
                       "minItems": 1,
-                      "description": "Trusted ID-JAG issuers. These values are never published in OAuth metadata.",
+                      "description": "Trusted ID-JAG issuers. These values are never published in OAuth metadata. Omit to trust this policy's browser-login IdP.",
                       "items": {
                         "type": "object",
                         "additionalProperties": false,
-                        "required": ["issuer", "jwksUrl"],
+                        "dependentRequired": {
+                          "issuer": ["jwksUrl"],
+                          "jwksUrl": ["issuer"]
+                        },
                         "properties": {
                           "issuer": {
                             "type": "string",
                             "format": "uri",
-                            "description": "Exact issuer URL expected in the ID-JAG iss claim."
+                            "description": "Exact issuer URL expected in the ID-JAG iss claim. Provide together with jwksUrl, or omit both to default to this policy's browser-login IdP."
                           },
                           "jwksUrl": {
                             "type": "string",
                             "format": "uri",
-                            "description": "JWKS URL used to verify ID-JAG signatures from this issuer."
+                            "description": "JWKS URL used to verify ID-JAG signatures from this issuer. Provide together with issuer, or omit both to default to this policy's browser-login IdP."
                           },
                           "expectedClientIds": {
                             "type": "array",

package/docs/policies/mcp-clerk-oauth-inbound/schema.json

@@ -82,6 +82,84 @@
                 }
               }
             },
+            "idJag": {
+              "description": "Optional Identity Assertion JWT Authorization Grant (ID-JAG / XAA) support for the gateway token endpoint.",
+              "oneOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["enabled"],
+                  "properties": {
+                    "enabled": {
+                      "const": false,
+                      "description": "Disable ID-JAG support."
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["enabled"],
+                  "properties": {
+                    "enabled": {
+                      "const": true,
+                      "description": "Enable ID-JAG support."
+                    },
+                    "trustedIssuers": {
+                      "type": "array",
+                      "minItems": 1,
+                      "description": "Trusted ID-JAG issuers. These values are never published in OAuth metadata. Omit to trust this policy's browser-login IdP.",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "dependentRequired": {
+                          "issuer": ["jwksUrl"],
+                          "jwksUrl": ["issuer"]
+                        },
+                        "properties": {
+                          "issuer": {
+                            "type": "string",
+                            "format": "uri",
+                            "description": "Exact issuer URL expected in the ID-JAG iss claim. Provide together with jwksUrl, or omit both to default to this policy's browser-login IdP."
+                          },
+                          "jwksUrl": {
+                            "type": "string",
+                            "format": "uri",
+                            "description": "JWKS URL used to verify ID-JAG signatures from this issuer. Provide together with issuer, or omit both to default to this policy's browser-login IdP."
+                          },
+                          "expectedClientIds": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "description": "Optional allow-list of client IDs accepted from this issuer. The ID-JAG client_id must still match the authenticated token-endpoint client."
+                          },
+                          "subjectMapping": {
+                            "type": "string",
+                            "enum": [
+                              "iss_prefix",
+                              "iss_tenant_prefix",
+                              "sub_id_only"
+                            ],
+                            "default": "iss_prefix",
+                            "description": "How the ID-JAG subject is mapped into the gateway subject ID."
+                          }
+                        }
+                      }
+                    },
+                    "authorizationDetailsTypesAllowed": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "description": "Optional allow-list of RFC 9396 authorization_details type values accepted from ID-JAGs."
+                    }
+                  }
+                }
+              ]
+            },
             "browserLoginOverrides": {
               "type": "object",
               "description": "Optional overrides for the derived browser-login settings.",

package/docs/policies/mcp-cognito-oauth-inbound/schema.json

@@ -98,6 +98,84 @@
                 }
               }
             },
+            "idJag": {
+              "description": "Optional Identity Assertion JWT Authorization Grant (ID-JAG / XAA) support for the gateway token endpoint.",
+              "oneOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["enabled"],
+                  "properties": {
+                    "enabled": {
+                      "const": false,
+                      "description": "Disable ID-JAG support."
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["enabled"],
+                  "properties": {
+                    "enabled": {
+                      "const": true,
+                      "description": "Enable ID-JAG support."
+                    },
+                    "trustedIssuers": {
+                      "type": "array",
+                      "minItems": 1,
+                      "description": "Trusted ID-JAG issuers. These values are never published in OAuth metadata. Omit to trust this policy's browser-login IdP.",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "dependentRequired": {
+                          "issuer": ["jwksUrl"],
+                          "jwksUrl": ["issuer"]
+                        },
+                        "properties": {
+                          "issuer": {
+                            "type": "string",
+                            "format": "uri",
+                            "description": "Exact issuer URL expected in the ID-JAG iss claim. Provide together with jwksUrl, or omit both to default to this policy's browser-login IdP."
+                          },
+                          "jwksUrl": {
+                            "type": "string",
+                            "format": "uri",
+                            "description": "JWKS URL used to verify ID-JAG signatures from this issuer. Provide together with issuer, or omit both to default to this policy's browser-login IdP."
+                          },
+                          "expectedClientIds": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "description": "Optional allow-list of client IDs accepted from this issuer. The ID-JAG client_id must still match the authenticated token-endpoint client."
+                          },
+                          "subjectMapping": {
+                            "type": "string",
+                            "enum": [
+                              "iss_prefix",
+                              "iss_tenant_prefix",
+                              "sub_id_only"
+                            ],
+                            "default": "iss_prefix",
+                            "description": "How the ID-JAG subject is mapped into the gateway subject ID."
+                          }
+                        }
+                      }
+                    },
+                    "authorizationDetailsTypesAllowed": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "description": "Optional allow-list of RFC 9396 authorization_details type values accepted from ID-JAGs."
+                    }
+                  }
+                }
+              ]
+            },
             "browserLoginOverrides": {
               "type": "object",
               "description": "Optional overrides for the derived browser-login settings.",