zuplo 6.72.2 → 6.72.7

package/docs/analytics/access-and-entitlements.md

@@ -7,56 +7,49 @@ sidebar_label: "Access & Entitlements"
 
 - Confirm whether your account can see analytics.
 - Find out how many days of history you have access to.
-- Understand the trial banner or the demo mode link.
+- Understand the trial banner.
 
-## Plan requirements
+## Availability
 
-Analytics must be enabled on your account. Without it, the Analytics page shows
-an upsell view with a **Contact Sales** call-to-action and no charts.
+Analytics is included on every plan. Your plan determines how much history you
+can query — see [Data retention](#data-retention). If the Analytics page shows
+an upsell view with a **Contact Sales** call-to-action instead of charts, your
+account has analytics disabled — contact your Zuplo account team.
 
 ## Free trial
 
-New accounts with analytics enabled get an automatic free trial. The trial:
+Every new account gets an automatic 14-day observability trial. During the
+trial:
 
-- Runs for the same number of days as your account's retention window.
-- Shows a banner across the top of the Analytics page: "You're on a {N}-day
-  preview of Analytics, {N} days left."
-- Includes two call-to-actions: **View demo →** (loads the dashboard with sample
-  data) and **Contact sales**.
+- You get longer history windows for analytics, logs, and traces than your plan
+  includes. Accounts on self-serve plans get the Builder/Business windows (7
+  days of analytics, 1 day of logs and traces); Enterprise trial accounts get
+  the Enterprise windows. See [Data retention](#data-retention).
+- A banner appears across the top of the Observability tabs: "You're on a 14-day
+  trial of Zuplo Observability — {N} days left", with a **Contact sales** link.
 
-Accounts on the legacy analytics version are not eligible for the trial. They
-continue to use the previous experience.
+When the trial ends, your plan's own history windows apply.
 
-:::note
-
-The trial banner notes that the charts may look sparse if your account hasn't
-yet generated much traffic. Use **View demo →** to see what a fully populated
-dashboard looks like.
+## Data retention
 
-:::
+Each account has history windows for analytics, logs, and traces. The windows
+depend on your plan:
 
-## Data retention
+| Plan               | Analytics history | Log & trace history |
+| ------------------ | ----------------- | ------------------- |
+| Free               | 1 day             | Live (15 minutes)   |
+| Builder / Business | 7 days            | 1 day               |
+| Enterprise         | 30 days           | 3 days              |
 
-Each account has an analytics history window measured in days. The window
-controls:
+The analytics window controls:
 
 - How far back you can scroll using the time-range picker.
 - Which presets in the picker are available. Presets longer than your window are
-  locked with an **Upgrade for [preset]** tooltip.
+  locked and show an **Upgrade** badge; hover one for details.
 - The maximum start and end values when you pick a custom range.
 
-If you need a longer window, contact your Zuplo account team.
-
-## Demo mode
-
-Append `?demo=true` to the Analytics URL, or click **View demo →** in the trial
-banner, to switch into demo mode. In demo mode:
-
-- Charts and tables are populated with synthetic sample data.
-- A persistent banner reads: "You're viewing the Analytics demo with sample
-  data. Your real analytics aren't shown here."
-
-Remove the `demo` parameter from the URL to return to your real data.
+If you need a longer window, contact your Zuplo account team — custom retention
+is available on Enterprise plans.
 
 ## Scope: account vs project
 

package/docs/analytics/overview.md

@@ -32,7 +32,7 @@ Analytics lives in the **Observability** tab of the Zuplo Portal, alongside
 ## What's in this section
 
 - [Access and entitlements](./access-and-entitlements.md): plans, free trial,
-  demo mode, retention.
+  retention.
 - [Shared controls](./shared-controls.md): time range, filters, environment
   selector, banners, URL state.
 - Sections:
@@ -56,12 +56,13 @@ You'll see a subset of sections depending on your plan and project setup:
 
 | Section   | When it appears                                            |
 | --------- | ---------------------------------------------------------- |
-| Requests  | All accounts with analytics enabled.                       |
+| Requests  | All accounts.                                              |
 | Origins   | The project uses managed-edge origins.                     |
-| Consumers | All accounts with analytics enabled.                       |
-| Agents    | All accounts with analytics enabled.                       |
+| Consumers | All accounts.                                              |
+| Agents    | All accounts.                                              |
 | MCP       | The project type is **standard** and the project uses MCP. |
 | GraphQL   | The project proxies a GraphQL API.                         |
 
-If you don't see Analytics at all, your account likely doesn't have analytics
-enabled. See [Access and entitlements](./access-and-entitlements.md).
+Analytics is included on every plan. If you don't see Analytics at all, your
+account may have it disabled — see
+[Access and entitlements](./access-and-entitlements.md).

package/docs/analytics/reference/url-parameters.md

@@ -8,7 +8,7 @@ view.
 
 ## When to use this
 
-- Build a permalink to a specific time window, filter set, or demo view.
+- Build a permalink to a specific time window or filter set.
 - Embed an Analytics link in a runbook, postmortem, or dashboard.
 - Understand what each query parameter does.
 
@@ -16,11 +16,9 @@ view.
 
 | Parameter      | Example                                                | Effect                                                                                    |
 | -------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
-| `time`         | `?time=7d`                                             | Apply a preset. Values: `1h`, `6h`, `24h`, `3d`, `7d`, `14d`, `28d`, `60d`, `90d`.        |
+| `time`         | `?time=7d`                                             | Apply a preset. Values: `1h`, `6h`, `24h`, `3d`, `7d`, `14d`, `28d`, `30d`, `60d`, `90d`. |
 | `start`, `end` | `?start=2026-05-01T00:00:00Z&end=2026-05-15T00:00:00Z` | Custom range as ISO-8601 datetimes. Overrides `time` when both are present.               |
 | `filter`       | `?filter=httpStatus:class:5xx`                         | Add a filter as `<field>:<matchmode>:<value>`. Repeat the parameter for multiple filters. |
-| `demo`         | `?demo=true`                                           | Demo mode (sample data instead of your real analytics).                                   |
-| `preview`      | `?preview=1`                                           | Legacy preview mode.                                                                      |
 
 ## Match modes for `filter`
 
@@ -48,12 +46,6 @@ Custom range with two filters:
 ?start=2026-05-01T00:00:00Z&end=2026-05-08T00:00:00Z&filter=country:equals:US&filter=httpMethod:equals:POST
 ```
 
-Open the demo:
-
-```
-?demo=true
-```
-
 ## Sharing
 
 The recipient sees the same view, provided they have access to the project or

package/docs/analytics/shared-controls.md

@@ -18,7 +18,7 @@ State persists to the URL so you can share or bookmark any view.
 The time range picker controls every chart, table, and KPI in the active
 section.
 
-**Presets.** Last 1h, 6h, 24h, 3d, 7d, 14d, 28d, 60d, 90d.
+**Presets.** Last 1h, 6h, 24h, 3d, 7d, 14d, 28d, 30d, 60d, 90d.
 
 **Custom range.** Use the datetime-local inputs for **Start** and **End**. Both
 fields are clamped to your account's retention window.
@@ -80,8 +80,6 @@ There's no separate share button.
 | `time`         | `?time=7d`                                             | Apply a preset.                                         |
 | `start`, `end` | `?start=2026-05-01T00:00:00Z&end=2026-05-15T00:00:00Z` | Custom range. Overrides `time`.                         |
 | `filter`       | `?filter=httpStatus:class:5xx`                         | Add a filter. Repeat the parameter for multiple values. |
-| `demo`         | `?demo=true`                                           | Demo mode (sample data).                                |
-| `preview`      | `?preview=1`                                           | Legacy preview mode.                                    |
 
 See [URL parameters](./reference/url-parameters.md) for the full reference.
 
@@ -94,13 +92,8 @@ a refetch.
 
 ## Banners
 
-Banners appear at the top of the page in this priority order:
-
-1. **Preview banner**: when `preview=1` is set. Indicates legacy preview mode.
-2. **Demo banner**: when `demo=true` is set. Reminds you sample data is shown
-   instead of your real analytics.
-3. **Trial banner**: for new accounts with analytics. Shows days remaining and
-   offers **View demo →** and **Contact Sales**.
+During the 14-day observability trial, a banner appears at the top of the page
+showing the days remaining, with a **Contact sales** link.
 
 ## Loading and empty states
 

package/docs/analytics/tabs/agents.md

@@ -74,9 +74,9 @@ The filter bar applies. `originHost` is not applicable here. See
 ## Troubleshooting
 
 **The Agents section is empty.** Either no classified agents called your gateway
-in the window, or your retention window doesn't yet include any agent traffic.
-Try the demo with **View demo →** in the trial banner to see what a populated
-view looks like. See [Access and entitlements](../access-and-entitlements.md).
+in the window, or your
+[retention window](../access-and-entitlements.md#data-retention) doesn't yet
+include any agent traffic.
 
 **I see a known agent in my logs but not here.** The classifier is conservative;
 it labels traffic that clearly matches a known agent fingerprint. Generic SDK

package/docs/analytics/tabs/requests.md

@@ -91,7 +91,5 @@ not include any geolocated requests.
 that breakdown. Top-10 plus 50 covers up to 60 distinct values; beyond that,
 narrow the time range or add a filter.
 
-**My charts look sparse.** If your account is new, the trial banner across the
-top calls this out. Click **View demo →** in the banner to see what a fully
-populated dashboard looks like. See
-[Access and entitlements](../access-and-entitlements.md).
+**My charts look sparse.** New accounts may not have generated much traffic yet.
+Charts fill in as requests flow through your gateway.

package/docs/articles/accounts/audit-logs.mdx

@@ -1,5 +1,5 @@
 ---
-title: Audit Logs
+title: Account Audit Logs
 sidebar_label: Audit Logs
 ---
 
@@ -211,8 +211,8 @@ exceed 30 days. The start date must be before the end date.
 
 :::tip
 
-Account audit logs track administrative activities. To log API request and
-response data flowing through the gateway, see the
-[Audit Log Plugin](../../programmable-api/audit-log.mdx).
+Account audit logs track administrative activities in your Zuplo account. To
+record an audit trail of the requests flowing through your gateway, see
+[Audit Logging](../audit-logging.mdx).
 
 :::

package/docs/articles/audit-logging.mdx

@@ -0,0 +1,65 @@
+---
+title: Audit Logging
+sidebar_label: Overview
+---
+
+Audit logs answer the question "who did what through your API, and when?" —
+providing a structured, searchable record of every request and business event
+that flows through your gateway. This page explains why audit logging matters
+and the options Zuplo gives you for capturing an audit trail.
+
+## Why audit logging?
+
+Audit logging plays a critical role in API security: it lets you detect and
+investigate issues such as unauthorized access or permission elevation, and
+reconstruct exactly what happened to a resource after the fact. It's also a hard
+requirement for many compliance certifications (SOC 2, ISO 27001, HIPAA, PCI
+DSS) and a common buying criterion for enterprise customers of your API.
+
+Unlike request logs — which are optimized for debugging and operational
+visibility — audit logs are structured business records: each event identifies
+an actor, an action, and the resources affected, in a stable format you can
+retain, search, and hand to an auditor.
+
+## Options for audit logging
+
+Zuplo supports two approaches, depending on where you want your audit trail to
+live:
+
+1. **[Zuplo Audit Logs](./audit-logs.mdx)** — the recommended approach for most
+   APIs. Add a single policy and Zuplo records, stores, and indexes a structured
+   audit event for every request. You can search the events in the Zuplo Portal,
+   query them through the Zuplo API, and export them to a SIEM. No code or
+   infrastructure required.
+2. **[Custom audit logs](./custom-audit-logs.mdx)** — write a small custom
+   policy that sends audit events to any external audit provider (for example,
+   WorkOS Audit Logs). Full control over the event format and destination.
+
+|              | Zuplo Audit Logs          | Custom audit logs     |
+| ------------ | ------------------------- | --------------------- |
+| Setup        | Add a policy              | Write policy code     |
+| Storage      | Managed by Zuplo          | Your provider         |
+| Viewing      | Zuplo Portal + Zuplo API  | Your provider's tools |
+| Availability | Enterprise (free to test) | All plans             |
+
+Zuplo Audit Logs is an enterprise feature, but anyone can use it for free for
+development and testing purposes.
+
+## Gateway audit logs versus account audit logs
+
+Zuplo has two separate audit trails — the options above all concern the first:
+
+- **Gateway audit logs** record traffic through _your API_: requests from your
+  API's consumers and custom events emitted by your gateway code.
+- **[Account audit logs](./accounts/audit-logs.mdx)** record administrative
+  activity in _your Zuplo account_: project changes, team member management,
+  deployments, and other portal and API operations.
+
+## Next steps
+
+- [Zuplo Audit Logs](./audit-logs.mdx) — enable the built-in feature and start
+  recording events
+- [Custom audit logs](./custom-audit-logs.mdx) — send audit events to an
+  external provider
+- [Audit Logs policy reference](../policies/audit-log-inbound.mdx) — all
+  configuration options and the full event shape

package/docs/articles/audit-logs.mdx

@@ -0,0 +1,222 @@
+---
+title: Zuplo Audit Logs
+sidebar_label: Zuplo Audit Logs
+---
+
+Zuplo's Audit Logs feature gives you a complete
+[audit trail](./audit-logging.mdx) of your API with a single policy: the gateway
+records a structured event for every request, stores the events for you, and
+makes them available in the Zuplo Portal and through the Zuplo API.
+
+<EnterpriseFeature name="Audit Logs" />
+
+## How it works
+
+<Diagram height="h-56">
+  <DiagramNode id="client">Client</DiagramNode>
+  <DiagramGroup id="zuplo" label="Zuplo">
+    <DiagramNode id="gateway" variant="zuplo">
+      Gateway (Audit Logs policy)
+    </DiagramNode>
+    <DiagramNode id="store">Audit log storage</DiagramNode>
+  </DiagramGroup>
+  <DiagramNode id="consumers">Portal / API / SIEM</DiagramNode>
+  <DiagramEdge from="client" to="gateway" />
+  <DiagramEdge from="gateway" to="store" label="events" />
+  <DiagramEdge from="store" to="consumers" />
+</Diagram>
+
+Add the [Audit Logs policy](../policies/audit-log-inbound.mdx) to any route and
+the gateway records one structured audit event per request — who made the
+request, what they called, and the outcome. You can also emit your own custom
+events (for example, "account deleted") from handlers and custom policies. Every
+event follows the [CloudEvents](https://cloudevents.io/) 1.0 format.
+
+Zuplo stores the events for you, grouped by environment — production, preview,
+and working copy environments each write to their own bucket. You don't need a
+database, logging service, or any other infrastructure of your own.
+
+## Recording audit events
+
+### Automatic request events
+
+Add the policy to the routes you want audited. Typically that's any route that
+modifies data, though depending on your API you may want it on sensitive read
+operations as well (for example, retrieving a secret).
+
+```json title="config/policies.json"
+{
+  "name": "audit-logs",
+  "policyType": "audit-log-inbound",
+  "handler": {
+    "export": "AuditLogInboundPolicy",
+    "module": "$import(@zuplo/runtime)"
+  }
+}
+```
+
+Each request through the policy produces an event of type
+`com.zuplo.api.request` capturing the actor, HTTP method and path, response
+status, caller IP address, and geolocation.
+
+Audit events can contain personal or sensitive data. The policy's `include`
+options let you turn off individual fields (query parameters, user identity, IP
+address, geolocation) to satisfy your own data-handling and personally
+identifiable information (PII) policies, and `samplingRate` lets you capture
+only a fraction of requests on high-volume routes. See the
+[policy reference](../policies/audit-log-inbound.mdx) for all options.
+
+### Custom events
+
+Beyond the automatic per-request event, record your own domain events from a
+handler or custom policy with the static `AuditLogInboundPolicy.log()` method.
+Only `type` is required — Zuplo fills in the actor, timestamp, request ID, and
+other context fields automatically from the request:
+
+```ts title="modules/handlers.ts"
+import {
+  AuditLogInboundPolicy,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export async function deleteAccount(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const accountId = request.params.accountId;
+
+  // ...perform the delete...
+
+  AuditLogInboundPolicy.log(context, {
+    type: "com.acme.account.deleted",
+    subject: `account|${accountId}`,
+    resources: [{ type: "account", id: accountId }],
+    success: true,
+  });
+
+  return new Response(null, { status: 204 });
+}
+```
+
+Audit logging is best-effort by design: `log()` never throws and never blocks or
+fails the request, even if an event can't be recorded.
+
+## Viewing audit logs in the portal
+
+To browse and search your audit logs, open your project's
+[**Services**](https://portal.zuplo.com/+/account/project/services) page in the
+Zuplo Portal and select the **Audit Logs** tile for the environment you want to
+inspect.
+
+The events view lets you:
+
+- Filter events by time range, event type, actor, and subject
+- See the top event types and most active actors for the selected window
+- Select any event to inspect the full event payload
+
+## Querying audit logs with the API
+
+Everything in the portal is backed by the Zuplo API, so you can query audit logs
+programmatically — for scripting, custom dashboards, or exporting to other
+systems. Authenticate with a [Zuplo API key](./accounts/zuplo-api-keys.mdx) and
+query events by bucket name. Your bucket name is shown on the **Services** page
+in the portal (it's the same bucket used by the API Key Service).
+
+```bash
+curl "https://dev.zuplo.com/v1/audit-logs/$BUCKET_NAME/events?type=com.zuplo.api.request&startDate=2026-07-01T00:00:00Z&endDate=2026-07-07T00:00:00Z" \
+  -H "Authorization: Bearer $ZUPLO_API_KEY"
+```
+
+```json
+{
+  "data": [
+    {
+      "specversion": "1.0",
+      "id": "e6c8b1f2-2c3d-4a5b-9e10-1f2a3b4c5d6e",
+      "type": "com.zuplo.api.request",
+      "time": "2026-07-05T18:12:04.123Z",
+      "actorsub": "user|12356",
+      "actortype": "user",
+      "requestid": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
+      "httpmethod": "GET",
+      "httpurl": "/customers/12345?expand=orders",
+      "httpstatus": 200,
+      "success": true,
+      "ipaddress": "203.0.113.7",
+      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
+      "country": "US",
+      "region": "Washington",
+      "city": "Seattle"
+    }
+  ],
+  "pagination": { "limit": 20, "offset": 0, "total": 1, "hasMore": false }
+}
+```
+
+Two endpoints are available:
+
+- **Query events** — `GET /v1/audit-logs/{bucketId}/events` returns matching
+  events, filterable by `type`, `actorSub`, `subject`, and time range.
+- **Aggregated stats** — `GET /v1/audit-logs/{bucketId}/stats` returns top-N
+  event counts grouped by event type or actor.
+
+The `bucketId` path parameter accepts either the bucket ID or the bucket name.
+Each query is limited to a 30-day window between `startDate` and `endDate`. See
+the [Audit Logs API reference](../api/audit-logs) for all parameters and
+response schemas.
+
+## Exporting audit logs to a SIEM
+
+Many organizations centralize audit trails in a SIEM (Splunk, Microsoft
+Sentinel, Datadog Cloud SIEM, and so on) to correlate API activity with other
+security signals, drive alerting, and meet long-term retention requirements. The
+events API is designed for this: run a scheduled job that pulls new events since
+its last checkpoint and forwards them to your SIEM.
+
+```ts
+const BASE_URL = "https://dev.zuplo.com/v1/audit-logs";
+
+// Run on a schedule (e.g. every 5 minutes). `startDate` is the checkpoint
+// saved by the previous run; `endDate` is the current time.
+async function exportAuditLogs(
+  bucketName: string,
+  startDate: string,
+  endDate: string,
+) {
+  let offset = 0;
+  let hasMore = true;
+  while (hasMore) {
+    const url = new URL(`${BASE_URL}/${bucketName}/events`);
+    url.searchParams.set("startDate", startDate);
+    url.searchParams.set("endDate", endDate);
+    url.searchParams.set("limit", "100");
+    url.searchParams.set("offset", String(offset));
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${process.env.ZUPLO_API_KEY}` },
+    });
+    const { data, pagination } = await response.json();
+    await sendToSiem(data); // e.g. Splunk HEC, Datadog Logs API, S3
+    offset += data.length;
+    hasMore = pagination.hasMore;
+  }
+}
+```
+
+Because every event is a CloudEvents document, most SIEMs can ingest the payload
+directly without transformation.
+
+Alternatively, if you'd rather send audit events to an external audit provider
+directly from the gateway instead of storing them in Zuplo, see
+[Custom Audit Logs](./custom-audit-logs.mdx).
+
+## Related resources
+
+- [Audit logging overview](./audit-logging.mdx) — why audit logging matters and
+  how the options compare
+- [Audit Logs policy reference](../policies/audit-log-inbound.mdx) — all
+  configuration options, custom event fields, and the full event shape
+- [Audit Logs API reference](../api/audit-logs) — query events and stats
+  programmatically
+- [Account audit logs](./accounts/audit-logs.mdx) — the audit trail of your
+  Zuplo account itself

package/docs/articles/connect-to-aws-alb-with-mtls.mdx

@@ -20,9 +20,9 @@ present an X.509 certificate that chains to a Certificate Authority (CA) in the
 ALB's trust store. Zuplo presents that client certificate on each outbound
 request, and the ALB rejects anything that can't.
 
-This guide covers the Zuplo side of that connection: uploading a client
-certificate and presenting it on requests to the ALB. It does **not** cover
-configuring the ALB itself — for that, follow the AWS documentation linked in
+This guide covers uploading a client certificate to Zuplo and presenting it on
+requests to the ALB. It does **not** cover configuring the ALB itself — for
+that, follow the AWS documentation linked in
 [Configure the ALB](#1-configure-the-alb).
 
 ## How it works
@@ -64,10 +64,13 @@ For background on the gateway-to-origin direction in general, see
 
 Before you begin, you need:
 
-- A client certificate and private key (PEM-encoded) issued by a CA. The same CA
-  must be uploaded to the ALB's trust store.
+- A PEM-encoded client certificate (`client-cert.pem`), matching private key
+  (`client-key.pem`), and public CA certificate or bundle (`client-ca.pem`). The
+  same CA must be in the ALB's trust store.
 - An AWS Application Load Balancer with an HTTPS listener you can configure for
   mTLS.
+- The AWS CLI installed and authenticated with permission to inspect the ALB's
+  listener and trust store.
 - The [Zuplo CLI](../cli/overview.mdx) installed and authenticated.
 
 ## 1/ Configure the ALB
@@ -93,7 +96,79 @@ edge.
 
 :::
 
-## 2/ Upload your client certificate to Zuplo
+## 2/ Validate the certificate and ALB trust
+
+Confirm that the listener uses verify mode and capture its trust store ARN:
+
+```bash
+aws elbv2 describe-listeners \
+  --listener-arns <HTTPS_LISTENER_ARN> \
+  --query 'Listeners[0].MutualAuthentication' \
+  --output json
+
+TRUST_STORE_ARN=$(aws elbv2 describe-listeners \
+  --listener-arns <HTTPS_LISTENER_ARN> \
+  --query 'Listeners[0].MutualAuthentication.TrustStoreArn' \
+  --output text)
+
+aws elbv2 describe-trust-stores \
+  --trust-store-arns "$TRUST_STORE_ARN" \
+  --query 'TrustStores[0].{Name:Name,Status:Status,CACertificates:NumberOfCaCertificates}' \
+  --output table
+```
+
+The listener mode should be `verify`, and the trust store status should be
+`ACTIVE`.
+
+Inspect the client certificate and verify its path against the CA certificate:
+
+```bash
+openssl x509 \
+  -in client-cert.pem \
+  -noout \
+  -subject \
+  -issuer \
+  -dates \
+  -purpose
+
+openssl verify \
+  -verbose \
+  -purpose sslclient \
+  -x509_strict \
+  -show_chain \
+  -CAfile client-ca.pem \
+  client-cert.pem
+```
+
+`SSL client` should report `Yes`, and verification should return
+`client-cert.pem: OK`. Also confirm that the certificate and private key match:
+
+```bash
+CERT_KEY_HASH=$(openssl x509 -in client-cert.pem -noout -pubkey | openssl sha256)
+PRIVATE_KEY_HASH=$(openssl pkey -in client-key.pem -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"
+```
+
+For the strongest offline check, run `openssl verify` with the exact CA bundle
+uploaded to the ALB trust store instead of `client-ca.pem`.
+
+If the ALB is reachable, test the TLS handshake directly:
+
+```bash
+curl --verbose \
+  --cert client-cert.pem \
+  --key client-key.pem \
+  "https://<ALB_HOSTNAME>/<TEST_PATH>"
+```
+
+Use a hostname covered by the ALB's server certificate. Any HTTP response,
+including a `401`, `403`, or `404`, shows that the TLS handshake completed; a
+client certificate failure occurs before an HTTP response is produced.
+
+## 3/ Upload your client certificate to Zuplo
 
 Use the Zuplo CLI to upload the client certificate and private key to your
 project. The CA that issued this certificate must already be in the ALB's trust
@@ -119,7 +194,7 @@ when you create the certificate.
 
 :::
 
-## 3/ Present the certificate on requests to the ALB
+## 4/ Present the certificate on requests to the ALB
 
 Reference the uploaded certificate by name when the gateway forwards requests to
 the ALB. Use the ALB's DNS name (or a custom domain pointed at it) as the
@@ -162,7 +237,7 @@ export default async function (request: ZuploRequest, context: ZuploContext) {
 }
 ```
 
-## 4/ Use environment variables across environments
+## 5/ Use environment variables across environments
 
 To use a different certificate per environment, store the certificate name in an
 [environment variable](./environment-variables.mdx) and reference it with the
@@ -226,11 +301,12 @@ received — usually a TLS handshake problem. Confirm that:
 
 ### The ALB rejects the certificate
 
-If the handshake completes but the ALB returns a `403`, the certificate is being
-presented but not trusted. Re-check the ALB trust store and confirm the listener
-is in **verify** mode, not passthrough. If your client certificate is issued by
-an intermediate CA, make sure the trust store contains the full chain back to
-the root.
+If the TLS handshake fails, re-check the ALB trust store and confirm the
+listener is in **verify** mode, not passthrough. If your client certificate is
+issued by an intermediate CA, make sure the trust store contains the CA chain
+required to validate the certificate. ALB connection logs can identify errors
+such as `ClientCertUntrusted`, `ClientCertPurposeInvalid`, `ClientCertExpired`,
+or `ClientCertNotYetValid`.
 
 ### No certificate appears to be sent