zuplo 6.68.15 → 6.68.17

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

@@ -186,23 +186,53 @@ The response will look like this:
 
 ### Roll a Consumer's Keys
 
-Sometimes you will want to create a new key and expire the current keys. Instead
-of calling the API for each key and manually creating a new key, you can simply
-call the roll key endpoint.
+Key rotation is a critical part of API key lifecycle management. Instant
+revocation of a key can break every system that depends on it, so Zuplo supports
+**rolling transitions** — creating a new key while keeping the old key active
+for a defined grace period.
+
+When you call the roll key endpoint, Zuplo:
+
+1. Creates a new key with no expiration for the consumer
+2. Sets the `expiresOn` date on all existing keys to the value you specify
+
+This gives consumers time to update their integration to the new key before the
+old one stops working.
+
+#### Choosing a transition period
+
+The right `expiresOn` value depends on how quickly consumers can update their
+keys:
+
+- **Leaked key response** — set `expiresOn` to a past date or within minutes.
+  Security incidents demand immediate action; a brief disruption is preferable
+  to continued exposure.
+- **Routine rotation** — 24 to 72 hours gives most teams enough time to
+  propagate the new key through CI/CD pipelines, environment variables, and
+  secret managers.
+- **Scheduled rotation** — for large organizations, 7 to 14 days accommodates
+  deploy freezes, multi-team coordination, and staged rollouts.
+
+:::tip{title="Multiple keys per consumer"}
+
+Consumers can also manage rotation themselves by creating a second key,
+deploying it, verifying traffic, and then deleting the old key on their own
+schedule. This pattern avoids any expiration deadline and puts the consumer in
+full control.
+
+:::
 
 :::tip{title="Tags for Request Authorization"}
 
-One useful feature of the API Key service is that most requests can have `tags`
-added to the query parameter even if they aren't get requests. This is useful
-when you want to call the API and ensure some basic condition is met without
-having to first do a GET to retrieve data on the object. For example, in the
-roll key request below the `orgId` tag is set on the request - this ensures that
-the consumer being updated is tagged with that org.
+Most API requests support `tags` as query parameters, even on non-GET requests.
+This lets you enforce conditions without a separate lookup. In the example
+below, the `orgId` tag ensures the consumer being updated belongs to that
+organization.
 
 :::
 
-The following call with set all existing keys to have the expiration date set in
-the request body and will create a new key without an expiration.
+The following call sets all existing keys to expire on the specified date and
+creates a new key without an expiration.
 
 ```shell
 export ORG_ID=1234
@@ -210,8 +240,9 @@ export CONSUMER_NAME=my-consumer
 curl \
   https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers/$CONSUMER_NAME/roll-key?tag.orgId=$ORG_ID \
   --request POST \
-  --header "Authorization: Bearer $API_KEY"
-  --data '{"expiresOn":"2023-04-18"}'
+  --header "Authorization: Bearer $API_KEY" \
+  --header "Content-Type: application/json" \
+  --data '{"expiresOn":"2026-04-19T00:00:00.000Z"}'
 ```
 
 ## Reference

package/docs/articles/api-key-leak-detection.mdx

@@ -3,29 +3,39 @@ title: API Key Leak Detection
 sidebar_label: Leak Detection
 ---
 
-## API Key Format
+## API key format enables leak detection
 
-Zuplo uses a specially formatted API Key structure that allows us to
-[partner with GitHub's secret scanning](https://github.blog/changelog/2022-07-13-zuplo-is-now-a-github-secret-scanning-partner/)
-to protect your users from accidentally leaked keys.
+Zuplo API keys use a structured format — `zpka_<random>_<checksum>` — that is
+specifically designed to support automated leak detection. The `zpka_` prefix
+allows scanning tools to identify Zuplo keys using a simple regex pattern, and
+the checksum suffix allows the scanner to verify that a matched string is a real
+Zuplo key (not a false positive) without making a database call.
 
-We think the safety of your API key consumers is paramount, so this feature is
-available to all Zuplo customers, including free.
+This format is what makes Zuplo a
+[GitHub secret scanning partner](https://github.blog/changelog/2022-07-13-zuplo-is-now-a-github-secret-scanning-partner/).
+Leak detection is available to all Zuplo customers, including free.
 
-## API Key Leak Detection
+## How leak detection works
 
 API keys should never be stored in source control. Accidentally committing API
-keys to source control is a common attack vector that leads to compromises of
-organizations both large and small.
+keys is a common attack vector that leads to compromises of organizations both
+large and small.
 
 Zuplo participates in
 [GitHub's Secret Scanning](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning)
-program to detect if your or your customer's API Keys are checked into source
-control on GitHub.
-
-If an API Key for your Zuplo API Gateway is compromised by checking it into a
-public or private GitHub repository, Zuplo will be notified and can take action
-immediately.
+program. When a Zuplo API key is committed to any GitHub repository — public or
+private — the following flow executes:
+
+1. **Detection** — GitHub's scanners match the `zpka_` prefix pattern across all
+   repository content, including code, config files, and commit history.
+2. **Checksum verification** — GitHub verifies the key's checksum signature to
+   confirm it is a structurally valid Zuplo key, filtering out false positives.
+3. **Notification to Zuplo** — GitHub sends the matched key to Zuplo's secret
+   scanning endpoint.
+4. **Database lookup** — Zuplo checks the key against its key service to
+   determine if it is an active key and which consumer it belongs to.
+5. **Customer notification** — Zuplo sends leak alerts via email and in-app
+   notification, including the repository URL where the key was found.
 
 ## Leak Notifications
 
@@ -40,22 +50,17 @@ send. If you need the full API Key please contact support.
 
 :::
 
-## Recommended Actions
-
-If you receive an alert that an API Key has been leaked, we recommend taking one
-of the following actions immediately.
-
-### Notify Your Customer
+## Recommended actions
 
-Notify your customer and ask them to login to your Zuplo powered developer
-portal and instruct them to roll the API Key. This way the old key is revoked
-and they get a new key.
+If you receive an alert that an API key has been leaked, take one of the
+following actions immediately.
 
-### Roll the API Key
+### Roll the API key
 
-You can use the
-[Zuplo API to roll the API Key](https://dev.zuplo.com/docs/routes#roll-consumer-keys)
-for the consumer. This will create a new key and revoke the old key.
+The fastest way to respond is to roll the consumer's key. Rolling creates a new
+key and sets an expiration on all existing keys for that consumer. You can set
+the `expiresOn` value to give the consumer a short transition period to update
+their integration, or omit it to revoke the old key immediately.
 
 ```bash
 export ACCOUNT_NAME="your-account-name"
@@ -69,7 +74,26 @@ curl --request POST \
   --header 'Content-Type: application/json' \
   --data '
 {
-  "expiresOn": "2024-01-01T00:00:00.000Z"
+  "expiresOn": "2026-04-17T00:00:00.000Z"
 }
 '
 ```
+
+:::caution
+
+For leaked keys, keep the transition period as short as possible. A leaked key
+remains valid until the expiration date you set. If the leak represents an
+active threat, revoke the key immediately by setting `expiresOn` to a past date
+or deleting the key directly.
+
+:::
+
+For more on key rotation patterns and choosing transition periods, see
+[Roll a Consumer's Keys](./api-key-api.mdx#roll-a-consumers-keys).
+
+### Notify your customer
+
+If the leaked key belongs to an end-user who manages their own keys through your
+developer portal, notify them and instruct them to roll the key themselves. The
+developer portal provides a self-serve roll key flow so consumers can generate a
+new key and revoke the old one without contacting your team.

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

@@ -3,14 +3,10 @@ title: API Keys Overview
 sidebar_label: Overview
 ---
 
-Zuplo allows developers to rapidly add API key based authentication to an API in
-minutes. There are several benefits to using Zuplo's API Key solution including
-
-- adheres to
-  [best practices of API Key implementation](https://zuplo.com/blog/2022/12/01/api-key-authentication)
-- includes [API Key Leak Detection & Notification](./api-key-leak-detection.mdx)
-- offers [out of the box and customizable solutions](./api-key-end-users.mdx)
-  for sharing API Keys
+Zuplo provides a fully managed API key authentication system that you can add to
+your API in minutes. Every key is validated at the edge across 300+ data
+centers, so authentication is fast for your consumers and offloads work from
+your backend.
 
 :::tip
 
@@ -19,30 +15,88 @@ To start using Zuplo API Keys in only a few minutes
 
 :::
 
-## Fully Managed API Key Solution
-
-Zuplo builds and manages a global API Key solution that can handle millions (or
-billions) of API Keys and a virtually unlimited throughput to scale to the most
-demanding services.
-
-The service handles global replication of API Keys allowing your end users to be
-authenticated to your API key with minimal latency. Keys are replicated around
-the world in only a few seconds. Similarly, when keys are revoked or deleted,
-the change replicates in seconds so that your API isn't open to unauthorized
-access.
-
-## API Key Authentication at the Edge
+## Why API keys?
+
+API keys are the standard authentication method for API-first companies like
+Stripe, Twilio, and SendGrid. They are the right choice when you need to
+authenticate an organization, system, or service rather than an individual user
+acting on their own behalf (which is where OAuth excels).
+
+Compared to JWT-based auth, API keys offer simpler developer experience — a
+single string in a header, easy to test with curl, and no token refresh flow.
+API keys are opaque, meaning they don't leak claim structure the way a decoded
+JWT does. And because each key maps to a consumer identity in Zuplo, you can
+revoke access instantly — you don't need to wait for a token to expire.
+
+For a deeper comparison, see the Zuplo blog post on
+[API key authentication best practices](https://zuplo.com/blog/api-key-authentication).
+
+## What you get with Zuplo API keys
+
+- **Thoughtful key format** — keys use a `zpka_` prefix, cryptographically
+  random body, and checksum signature. The prefix enables
+  [GitHub secret scanning](./api-key-leak-detection.mdx), the checksum allows
+  instant format validation without a database call, and the underscore
+  formatting means a double-click selects the entire key. See
+  [API key format](../concepts/api-keys.md#api-key-format) for the full
+  breakdown.
+- **Leak detection** — Zuplo is a
+  [GitHub secret scanning partner](./api-key-leak-detection.mdx). If a key is
+  committed to any GitHub repository, you are notified immediately.
+- **Self-serve key management** — give your API consumers a
+  [developer portal](./api-key-end-users.mdx) where they can create, view, roll,
+  and revoke their own keys.
+- **Edge validation** — keys are validated at the edge, keeping latency low and
+  your backend protected. See
+  [how validation works](../concepts/api-keys.md#how-validation-works) for
+  details on caching and replication.
+- **Key rotation with transition periods** — the
+  [roll-key API](./api-key-api.mdx#roll-a-consumers-keys) creates a new key and
+  sets an expiration on existing keys, so consumers have time to migrate without
+  downtime.
+
+## Fully managed global infrastructure
+
+Zuplo builds and manages the API key infrastructure so you don't have to. The
+service handles key storage, global replication, edge caching, and validation at
+scale — supporting millions of keys and virtually unlimited throughput.
+
+Keys replicate around the world in seconds. When a key is created, revoked, or
+deleted, the change propagates to all 300+ edge locations within seconds,
+ensuring your API is never open to unauthorized access for longer than the
+configured cache TTL.
+
+## How authentication works
+
+When a request arrives at Zuplo with an API key, the
+[API Key Authentication policy](../policies/api-key-inbound.mdx) validates it
+through a multi-step process:
+
+1. **Format check** — the key is checked for the correct `zpka_` prefix and
+   structure. Malformed keys are rejected immediately without any network call.
+2. **Checksum validation** — the key's built-in checksum signature is verified.
+   This catches typos and garbage keys in microseconds.
+3. **Cache lookup** — the edge checks its local cache for this key. If the key
+   was recently validated (or recently rejected), the cached result is used.
+4. **Key service lookup** — if the key isn't cached, Zuplo's globally
+   distributed key service is queried. The result is then cached for the
+   configured TTL (default 60 seconds).
+
+After successful validation, `request.user` is populated with the consumer's
+identity and metadata, which downstream policies and handlers can use for
+authorization, rate limiting, and routing. See
+[how validation works](../concepts/api-keys.md#how-validation-works) for more
+details.
+
+:::note
+
+The `cacheTtlSeconds` option on the API Key Authentication policy controls how
+long validation results are cached at each edge location. Higher values reduce
+latency but delay the effect of key revocation. A revoked key could still be
+accepted for up to `cacheTtlSeconds` after revocation. The default of 60 seconds
+is a good balance for most use cases.
 
-Using Zuplo's API Key Authentication policy, your API is secured from
-unauthorized access. Authorization checks happen at the edge in 300+ data
-centers around the world. This keeps load off your backend and keeps your API
-fast for your end-users.
-
-Zuplo manages all the complexity of replication, caching, and verifying your API
-keys so you don't have to.
-
-Adding API Key authentication using Zuplo takes only a few minutes.
-[See the quickstart to get started](../articles/step-3-add-api-key-auth.mdx).
+:::
 
 ## Key Concepts
 
@@ -92,9 +146,9 @@ API Keys are the actual string value used to authenticate with an API. Unlike
 some other forms of bearer tokens, API Keys don't contain any actual data within
 the key itself.
 
-Zuplo API Keys are prefixed with the string `zpka_` followed by
-cryptographically random characters and a signature. While Zuplo's API Key
-management service supports custom key formats (enterprise plan required), the
-structured format our the key enables us to offer
-[key leak detection services](./api-key-leak-detection.mdx) to keep your API
-secure.
+Zuplo API Keys use a structured format: a `zpka_` prefix, a cryptographically
+random body, and a checksum signature. This format enables
+[leak detection via GitHub secret scanning](./api-key-leak-detection.mdx) and
+allows instant format validation without a database call. Zuplo's API Key
+management service also supports custom key formats (enterprise plan required),
+though custom formats lose leak detection support.

package/docs/articles/secure-tunnel.mdx

@@ -19,9 +19,9 @@ private API. The benefits of a secure tunnel are:
 
 ## How does the Tunnel Work?
 
-The Zuplo tunnel can run on virtually any infrastructure. The most common way
-users install the tunnel is as a Docker container, but we can provide you a
-build in virtually any format (for example an Azure VM, etc.). The tunnel itself
+The Zuplo tunnel can run on virtually any Linux-based infrastructure. The most
+common way users install the tunnel is as a Docker container, but it can also
+run directly on a Linux virtual machine or bare-metal server. The tunnel itself
 is a lightweight service that when started makes an outbound connection to the
 Zuplo network and then through to your Zuplo Gateway.
 

package/docs/articles/tunnel-setup.mdx

@@ -4,6 +4,18 @@ title: Tunnel Setup & Use
 
 <EnterpriseFeature name="Secure tunneling" />
 
+:::caution{title="Platform Requirement"}
+
+The Zuplo tunnel service is officially supported on **Linux** only. The
+[`zuplo/tunnel` Docker image](https://hub.docker.com/r/zuplo/tunnel) is a Linux
+container, and any non-containerized deployment must target a Linux host. Cloud
+container platforms (AWS ECS, Azure Container Instances, GCP Cloud Run,
+Kubernetes) run Linux containers by default and require no extra configuration.
+If you are deploying on a virtual machine or bare metal, ensure the host runs a
+supported Linux distribution.
+
+:::
+
 ## Setting up Tunnels
 
 A tunnel is a way to expose your _internal services_ to the Zuplo gateway

package/docs/articles/tunnel-troubleshooting.mdx

@@ -7,6 +7,9 @@ work together. When setting up your tunnel it's common for traffic to initially
 not reach your destination initially. This is almost always caused by
 configurations (firewalls, VPCs, IAM rules, etc.) in your internal network.
 
+As a quick sanity check, verify that the tunnel is running on a
+[supported Linux host](./secure-tunnel.mdx) before investigating further.
+
 ## Tunnel status
 
 As a first step, check if the tunnel is up and running. You can use the

package/docs/concepts/api-keys.md

@@ -69,18 +69,78 @@ authorization and routing. Keep it small.
 **Tags** are key-value pairs used only for management (querying, filtering,
 organizing consumers via the API). Tags are not sent to the runtime.
 
-## API key format and leak detection
+## When to use API keys
 
-Zuplo API keys use a structured format prefixed with `zpka_` followed by
-cryptographically random characters and a signature. This format enables
-automatic [leak detection](../articles/api-key-leak-detection.mdx): if one of
-your keys appears in a public GitHub repository, Zuplo sends an alert with the
-token and the URL where it was found.
+API keys are the right authentication method when you need to identify an
+organization, system, or service calling your API. Companies like Stripe,
+Twilio, and SendGrid use API keys because they offer a simple developer
+experience — a single string in a header, easy to test with curl, and no token
+refresh flow.
 
-Leak detection is enabled automatically for all keys using the standard format.
+Use API keys when:
 
-See [API Key Leak Detection](../articles/api-key-leak-detection.mdx) for
-details.
+- Your API consumers are developers integrating server-to-server
+- You want simple, low-friction authentication (no OAuth dance)
+- You need to identify and rate-limit individual consumers
+- You want instant revocation capability (unlike JWTs, which are valid until
+  expiry)
+
+Use OAuth or JWT when:
+
+- You need to authenticate on behalf of an individual end-user
+- Your use case requires delegated authorization with scoped permissions
+- You are building a user-facing login flow
+
+API keys and JWT/OAuth are not mutually exclusive. Many APIs use API keys for
+system-level access and OAuth for user-level actions.
+
+## API key format
+
+Zuplo API keys use a structured three-part format:
+
+```
+zpka_<random>_<checksum>
+```
+
+Each part serves a specific purpose:
+
+- **`zpka_` prefix** — identifies the string as a Zuplo API key. This enables
+  automated [leak detection](../articles/api-key-leak-detection.mdx) via GitHub
+  secret scanning (scanners match the prefix pattern), helps support teams
+  identify key types during debugging, and distinguishes Zuplo keys from other
+  credentials in logs and config files.
+- **Random body** — a cryptographically random string that serves as the actual
+  credential. This portion is generated using a secure random source and
+  provides the entropy that makes each key unique.
+- **Checksum signature** — a suffix that allows instant format validation. When
+  a request arrives, Zuplo can verify the checksum mathematically in
+  microseconds to confirm the key is structurally valid before making any
+  network call. This rejects typos, truncated keys, and garbage strings without
+  touching the database.
+
+The underscore separators are also intentional — they ensure that a double-click
+on the key in most text editors and terminals selects the entire string,
+reducing the chance of accidentally copying a partial key.
+
+### Leak detection
+
+This key format is what makes Zuplo an official
+[GitHub secret scanning partner](https://github.blog/changelog/2022-07-13-zuplo-is-now-a-github-secret-scanning-partner/).
+If a Zuplo API key is committed to any GitHub repository, GitHub detects it,
+verifies the checksum, and notifies Zuplo. You receive an alert with the token
+and the repository URL where it was found. Leak detection is enabled
+automatically for all keys using the standard format and is available to all
+customers, including free.
+
+See [API Key Leak Detection](../articles/api-key-leak-detection.mdx) for the
+full scan flow and recommended response actions.
+
+:::note
+
+Enterprise customers can use custom key formats, but custom formats do not
+support leak detection.
+
+:::
 
 ## Self-serve key management
 

package/docs/dev-portal/auth-provider-api-identities.md

@@ -0,0 +1,190 @@
+---
+title: Custom API Identity Plugin
+sidebar_label: Custom API Identities
+navigation_icon: fingerprint
+description:
+  Learn how to create a custom API identity plugin for the Dev Portal to
+  authenticate API playground requests with OAuth JWT tokens or other custom
+  credentials.
+---
+
+The Dev Portal API playground allows users to make authenticated requests to
+your API. By default, users can enter credentials (such as API keys) directly in
+the playground's Authorize dialog. However, when your API uses OAuth or OpenID
+Connect for authentication, you need a custom API identity plugin to
+automatically attach the user's access token to playground requests.
+
+:::tip
+
+If you use Zuplo's built-in API key management, you do not need to create a
+custom identity plugin. API keys work automatically in the playground without
+any additional configuration.
+
+:::
+
+## When to use a custom identity plugin
+
+Use a custom API identity plugin when:
+
+- Your API requires OAuth 2.0 or OpenID Connect bearer tokens for
+  authentication.
+- You want to automatically attach the signed-in user's access token to
+  playground requests.
+- You need to apply custom authentication logic, such as using a specific token
+  format or adding extra headers.
+
+## Prerequisites
+
+Before creating an identity plugin, configure an
+[authentication provider](./zudoku/configuration/authentication.md) for the Dev
+Portal. The authentication provider handles user sign-in and token management.
+The identity plugin then bridges the user's session to the API playground.
+
+For example, using OpenID Connect:
+
+```ts title="zudoku.config.ts"
+const config = {
+  authentication: {
+    type: "openid",
+    clientId: "<your-client-id>",
+    issuer: "https://your-idp.example.com",
+  },
+};
+```
+
+## Creating an identity plugin
+
+Use `createApiIdentityPlugin` from `zudoku/plugins` to define how the playground
+authenticates API requests. The plugin provides a `getIdentities` function that
+returns one or more identities, each with an `authorizeRequest` function that
+modifies outgoing requests.
+
+### Using `signRequest`
+
+The simplest approach uses `context.authentication.signRequest()`, which
+automatically attaches the user's access token to the request:
+
+```ts title="zudoku.config.ts"
+import { createApiIdentityPlugin } from "zudoku/plugins";
+
+const config = {
+  authentication: {
+    type: "openid",
+    clientId: "<your-client-id>",
+    issuer: "https://your-idp.example.com",
+  },
+  plugins: [
+    createApiIdentityPlugin({
+      getIdentities: async (context) => [
+        {
+          id: "oauth-token",
+          label: "OAuth Token",
+          authorizeRequest: (request) => {
+            return context.authentication?.signRequest(request);
+          },
+        },
+      ],
+    }),
+  ],
+};
+```
+
+### Using `getAccessToken`
+
+If you need more control over how the token is applied, use
+`context.authentication.getAccessToken()` to retrieve the token directly. This
+is useful when you need to set a specific header format or add the token to a
+query parameter:
+
+```ts title="zudoku.config.ts"
+import { createApiIdentityPlugin } from "zudoku/plugins";
+
+const config = {
+  authentication: {
+    type: "openid",
+    clientId: "<your-client-id>",
+    issuer: "https://your-idp.example.com",
+  },
+  plugins: [
+    createApiIdentityPlugin({
+      getIdentities: async (context) => [
+        {
+          id: "jwt-bearer",
+          label: "JWT Bearer Token",
+          authorizeRequest: async (request) => {
+            const token = await context.authentication?.getAccessToken();
+
+            if (!token) {
+              throw new Error(
+                "No access token available. Please sign in again.",
+              );
+            }
+
+            request.headers.set("Authorization", `Bearer ${token}`);
+            return request;
+          },
+        },
+      ],
+    }),
+  ],
+};
+```
+
+## How it works
+
+When a user signs in to the Dev Portal and makes a request from the API
+playground:
+
+1. The Dev Portal displays the configured identities as selectable options in
+   the playground.
+2. When the user selects an identity and sends a request, the `authorizeRequest`
+   function runs before the request is sent.
+3. The function modifies the request (typically by adding an `Authorization`
+   header) and returns it.
+4. The playground sends the modified request to your API.
+
+## The `ApiIdentity` interface
+
+Each identity returned by `getIdentities` has the following properties:
+
+| Property           | Type                                                | Description                                                        |
+| ------------------ | --------------------------------------------------- | ------------------------------------------------------------------ |
+| `id`               | `string`                                            | A unique identifier for the identity.                              |
+| `label`            | `string`                                            | A human-readable name displayed in the playground identity picker. |
+| `authorizeRequest` | `(request: Request) => Request \| Promise<Request>` | A function that adds authentication credentials to the request.    |
+
+## Multiple identities
+
+You can return multiple identities from `getIdentities` to give users a choice
+of authentication methods:
+
+```ts title="zudoku.config.ts"
+createApiIdentityPlugin({
+  getIdentities: async (context) => [
+    {
+      id: "oauth-token",
+      label: "OAuth Token",
+      authorizeRequest: (request) => {
+        return context.authentication?.signRequest(request);
+      },
+    },
+    {
+      id: "custom-header",
+      label: "Custom API Header",
+      authorizeRequest: (request) => {
+        request.headers.set("X-Custom-Auth", "my-value");
+        return request;
+      },
+    },
+  ],
+});
+```
+
+## Related pages
+
+- [Authentication](./zudoku/configuration/authentication.md) - Configure a
+  sign-in provider for the Dev Portal.
+- [OAuth Security Schemes](./zudoku/configuration/oauth-security-schemes.md) -
+  Learn how OAuth security schemes work with the Dev Portal.
+- [Custom Plugins](./zudoku/custom-plugins.md) - Build other types of custom
+  plugins for the Dev Portal.

package/docs/policies/monetization-inbound/doc.md

@@ -59,6 +59,85 @@ import { MonetizationInboundPolicy } from "@zuplo/runtime";
 const meters = MonetizationInboundPolicy.getMeters(context);
 ```
 
+## Subscription data (for customization)
+
+The monetization policy validates the API key and attaches the **subscription**
+to the request context. You can read it later in your pipeline/handler to
+customize behavior (limits, feature flags, plan-based behavior, etc.).
+
+### Read subscription data
+
+```typescript
+import { MonetizationInboundPolicy } from "@zuplo/runtime";
+
+const subscription = MonetizationInboundPolicy.getSubscriptionData(context);
+
+if (!subscription) {
+  // The monetization policy may not have run yet, or the request was rejected earlier.
+  // Decide what behavior you want in this case.
+}
+```
+
+### Common fields you’ll likely use
+
+- **Identity**: `subscription.id`, `subscription.customerId`,
+  `subscription.name`
+- **Plan**: `subscription.plan.key`, `subscription.plan.version`
+- **Status & dates**: `subscription.status`, `subscription.activeFrom`,
+  `subscription.activeTo`, `subscription.nextBillingDate`
+- **Entitlements**: `subscription.entitlements[meterName]` →
+  `{ balance, usage, overage, hasAccess }`
+- **Payment** (when present): `subscription.paymentStatus.status`,
+  `subscription.paymentStatus.isFirstPayment`
+
+### Example: gate a feature by plan
+
+```typescript
+import { MonetizationInboundPolicy } from "@zuplo/runtime";
+
+const subscription = MonetizationInboundPolicy.getSubscriptionData(context);
+if (subscription?.plan.key !== "enterprise") {
+  return new Response("This feature requires the Enterprise plan.", {
+    status: 403,
+  });
+}
+```
+
+### Example: check entitlement access or remaining balance
+
+```typescript
+import { MonetizationInboundPolicy } from "@zuplo/runtime";
+
+const subscription = MonetizationInboundPolicy.getSubscriptionData(context);
+const entitlement = subscription?.entitlements?.["requests"];
+
+if (!entitlement?.hasAccess) {
+  return new Response("Your subscription does not include this meter.", {
+    status: 403,
+  });
+}
+
+// A simple “remaining” calculation you can use for UX or soft limits.
+const remaining = entitlement.balance - entitlement.usage;
+if (remaining <= 0) {
+  return new Response("Quota exceeded.", { status: 429 });
+}
+```
+
+### Example: customize response headers
+
+```typescript
+import { MonetizationInboundPolicy } from "@zuplo/runtime";
+
+const subscription = MonetizationInboundPolicy.getSubscriptionData(context);
+
+const nextResponse = new Response(response.body, response);
+if (subscription) {
+  nextResponse.headers.set("x-zuplo-plan", subscription.plan.key);
+}
+return nextResponse;
+```
+
 ## Meter merge behavior
 
 - The final hook merges `options.meters` and request meter increments from

package/docs/policies/monetization-inbound/intro.md

@@ -1,6 +1,6 @@
 The Monetization policy allows you to track and monetize the usage of your API
 resources, declaratively and programmatically.
 
-Follow our
-[Early Access: Getting Started with Monetization Guide](https://github.com/zuplo-samples/monetization-preview)
-to get started.
+Follow our official documentation
+[API Monetization with Zuplo](https://zuplo.com/docs/articles/monetization) to
+get started.

package/docs/programmable-api/zone-cache.mdx

@@ -3,10 +3,15 @@ title: ZoneCache
 sidebar_label: ZoneCache
 ---
 
-The ZoneCache stores data in a shared cache. This cache is in the same zone (the
-same data center or cluster) as your API - it's not globally distributed, but
-rather designed to be low-latency. Common uses include caching configuration,
-session, or other data that needs to be frequently accessed with low latency.
+The ZoneCache stores data in a shared cache that is local to a single zone (data
+center or cluster). Each zone maintains its own independent cache — data written
+in one zone is not synchronized or replicated to other zones. If the same data
+is needed in multiple zones, it must be written to each zone's cache
+independently.
+
+This makes ZoneCache ideal for caching configuration, reference data, or
+expensive API responses to reduce latency. It is not suitable for transactional,
+OLTP-style workloads where consistency across locations matters.
 
 The ZoneCache can store any JSON serializable data. Each cached item has a
 time-to-live (TTL) after which it expires and is removed from the cache. Each
@@ -112,15 +117,22 @@ promise rejections.
 
 ## When to use ZoneCache
 
-Use ZoneCache when you need low-latency access to frequently used data that's
-stored in a single zone. It's ideal for caching configuration data, session
-information, or results from external API calls that are expensive or slow to
-retrieve.
+ZoneCache works well for:
+
+- **Configuration and reference data** — API keys, feature flags, routing rules,
+  or other config that changes infrequently
+- **Expensive API responses** — results from slow or rate-limited upstream
+  services
+- **Computed data** — pre-processed results that are costly to regenerate
+
+:::caution{title="Not a distributed data store"}
 
-Avoid using ZoneCache for large datasets or data that needs to be globally
-distributed, as it's designed for small, simple objects within a single zone. It
-is also not suitable to be used as an OLTP to read/write important data, it's
-just a cache - very useful but not a database or key/value store.
+ZoneCache is a per-zone cache with **no cross-zone synchronization**. A `put()`
+in one data center has no effect on the cache in any other data center. Do not
+use it as a database, key/value store, or for any OLTP-style read/write
+workload. It is not appropriate for data where global consistency matters.
+
+:::
 
 ## Limits
 

package/package.json

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