@alvera-ai/platform-sdk 0.12.1-next.f7f8a3c → 0.12.1-next.g1cfe79a

package/.agent/AGENTS.md

@@ -114,19 +114,50 @@ platform. Two-step auth + client construction:
       email,
       password,
       tenantSlug,    // optional; omit for tenantless session
+      apiKey,        // REQUIRED. tenant-scoped sign-in is 401'd without a
+                     // resolvable X-API-Key; pass '' for root/tenantless
+                     // (the field is required by the type, inert on the wire)
     })
 
     // 2. build a typed client
     const api: PlatformApi = createIsolatedPlatformApi({
       baseUrl,
       sessionToken: session.sessionToken,
+      apiKey,        // rides as X-API-Key on every request
     })
 
+**Two credentials travel together on every request** (Firebase's
+"API key + ID token" pairing, not an either/or): the session token
+(`Authorization: Bearer …`) is what the platform authenticates and
+authorizes as — Bearer always wins identity; the **publishable API
+key** (`X-API-Key: …`) identifies the client and carries the
+origin policy — a `public_api` key declares `allowed_origins`, and
+a browser request's `Origin` is checked against the key that
+resolves. A Bearer session *inherits the origin policy of the key
+that minted it*. Where the key comes from: a tenant admin mints it
+in the platform's API-keys page (Settings → API Keys), or
+programmatically via `api.admin.createTenantApiKey(tenantSlug,
+{ name, data_access_mode })` (platform-admin-gated).
+
 Sessions come in three scopes:
 - **root** — Alvera root admin; user signup + confirmation
+  (`apiKey: ''` — no tenant to scope a key to)
 - **tenantless** — authenticated user with no tenant chosen yet;
   used once to create a tenant via `api.tenants.create(...)`
+  (`apiKey: ''`)
 - **tenant-scoped** — the canonical Bearer for tenant operations
+  (**requires a real tenant API key** — the login 401s with
+  `X-API-Key required to sign in to a tenant` otherwise)
+
+**Build apps tenant-scoped, and only tenant-scoped.** The root and
+tenantless scopes exist for the platform's own UI and for
+admin/bootstrap flows (signup, confirmation, tenant creation,
+test-suite setup) — they are NOT app-building surfaces; an app that
+holds a root or tenantless Bearer is misdesigned. An app
+authenticates against exactly one tenant with that tenant's
+publishable key. Likewise, connected apps are **single-tenant by
+construction** — one connected app per tenant, never one deployment
+serving many tenants (see `connected_apps.md`).
 
 Consumers holding multiple concurrent clients in the same file
 (e.g. integration tests that need root + tenantless + tenant-
@@ -189,7 +220,13 @@ business outcome.
    WORKFLOWS  (composition on top)
    ─────────
    workflows.md                  Filter + decision + action;
-                                  standard + agent-driven variants.
+                                  standard + agent-driven variants;
+                                  §8 watching a run.
+   messages.md                   The messages DATASET — what went
+                                  out, delivery status, engagement.
+   action_logs.md                The action_logs DATASET — per-
+                                  action outcomes, batch_id joins,
+                                  audience export.
 ```
 
 Axes are mostly disjoint but a few resources cross. AI Agents
@@ -217,6 +254,13 @@ wire name (snake_case):
     api.dataActivationClients           data_activation_clients.md
     api.workflows                       workflows.md
 
+Two corpus pages document DATASETS, not namespaces — read
+through `api.datasets` with SINGULAR dataset types (the plural
+forms are the SQL table names used by `executeSql`):
+
+    dataset type 'message'    (table messages)      messages.md
+    dataset type 'action_log' (table action_logs)   action_logs.md
+
 ## Cookbooks (Golden Path scenarios)
 
 `.agent/cookbook/<slug>.md` files are pure-markdown scenario

package/.agent/account_management.md

@@ -47,28 +47,51 @@ request.
 import { createSession } from '@alvera-ai/platform-sdk'
 
 // root admin (no tenant) — for confirmUser, signUp on behalf of, etc.
+// apiKey is required by the type but inert for non-tenant scopes — pass ''.
 const root = await createSession({
-  baseUrl, email: rootEmail, password: rootPassword,
+  baseUrl, email: rootEmail, password: rootPassword, apiKey: '',
 })
 
 // tenantless — authenticated user who has not picked a tenant yet
 const tenantless = await createSession({
-  baseUrl, email, password,
+  baseUrl, email, password, apiKey: '',
 })
 // tenantless.tenant === null
 
-// tenant-scoped — the canonical Bearer for tenant operations
+// tenant-scoped — the canonical Bearer for tenant operations.
+// REQUIRES a real tenant API key (sent as X-API-Key): the server 401s
+// with "X-API-Key required to sign in to a tenant" without one. The
+// minted Bearer inherits the origin policy of the key that minted it.
 const tenant = await createSession({
-  baseUrl, email, password, tenantSlug,
+  baseUrl, email, password, tenantSlug, apiKey: tenantApiKey,
 })
 // tenant.tenant.slug === tenantSlug
 // tenant.role.name   === 'tenant_admin' | 'member' | ...
 ```
 
+The tenant API key is minted by a tenant admin in the platform's
+API-keys page (Settings → API Keys), or programmatically via the
+platform-admin-gated side door:
+
+```typescript
+const { data: minted } = await rootApi.admin.createTenantApiKey(tenantSlug, {
+  name: 'Bootstrap Key',
+  data_access_mode: 'unregulated',
+})
+// minted.api_key — the publishable key value (thread into createSession)
+```
+
 See `AGENTS.md` "Sessions come in three scopes" for when each is
 appropriate. Tenantless is a transient state used once: to create
 a tenant (creator path) or accept an invitation (invitee path).
 
+**Scope discipline for app builders:** root and tenantless sessions
+are platform-UI / admin-bootstrap surfaces (signup, confirmation,
+tenant creation, test setup) — never ship them inside an app. An
+app authenticates **tenant-scoped against exactly one tenant**,
+with that tenant's publishable key; connected apps in particular
+are single-tenant by construction (`connected_apps.md`).
+
 ### Explicit teardown — `revokeSession`
 
 The inverse of `createSession`. Revokes the current Bearer on
@@ -214,7 +237,7 @@ client-side"). Use the returned slug for downstream calls.
 **Gotcha**: the response carries a `session_token` field, but this
 is an *incidental* token — do not treat it as a freshly minted
 tenant-scoped Bearer. The authoritative pattern is to call
-`createSession({ ..., tenantSlug })` after `tenants.create`. This
+`createSession({ ..., tenantSlug, apiKey })` after `tenants.create`. This
 gives a fresh Bearer with all role + tenant claims correctly
 populated.
 
@@ -223,6 +246,8 @@ populated.
 ```typescript
 const { data: tenants } = await api.tenants.list()
 // tenants.data: TenantResponse[] — every tenant the current Bearer can see
+// takes an optional Flop query (page/page_size/order_by/filters —
+// see type_naming.md "List response types")
 ```
 
 A root Bearer sees every tenant; a tenant-scoped Bearer typically
@@ -277,7 +302,7 @@ the invitation enum:
 | `'datalake_api'`        | Programmatic datalake access       | provisioned, not invited |
 
 ```typescript
-const session = await createSession({ baseUrl, email, password, tenantSlug })
+const session = await createSession({ baseUrl, email, password, tenantSlug, apiKey: tenantApiKey })
 // session.role.name === 'tenant_admin'   if accepted from a role: 'admin' invitation
 // session.role.name === 'member'         if accepted from a role: 'member' invitation
 // session.role.name === 'researcher'     if accepted from a role: 'researcher' invitation
@@ -327,7 +352,7 @@ const mine = invites.data.find(i => i.tenant.slug === tenantSlug)
 const { data: membership } = await tenantlessApi.invitations.accept(mine.id)
 
 // Then mint a tenant-scoped Bearer
-const session = await createSession({ baseUrl, email, password, tenantSlug })
+const session = await createSession({ baseUrl, email, password, tenantSlug, apiKey: tenantApiKey })
 // session.role.name === 'member'
 ```
 
@@ -419,7 +444,7 @@ treat as "already exists" via `api.tenants.list` lookup.
 
 2. **The `session_token` returned by `tenants.create` is
    incidental.** Always re-mint a fresh tenant-scoped Bearer via
-   `createSession({ ..., tenantSlug })` after creating a tenant.
+   `createSession({ ..., tenantSlug, apiKey })` after creating a tenant.
    This guarantees clean role+tenant claims on the Bearer.
 
 3. **Tenantless Bearer is a transient state.** Only two

package/.agent/action_logs.md

@@ -0,0 +1,139 @@
+# Action logs (datalake dataset)
+
+One row = one action outcome for one subject. Where `messages`
+answers "what went out", `action_logs` answers "what did each
+action do, per subject, per run" — including the actions that did
+NOT send (skipped, filtered, failed).
+
+Like `messages`, this is a **dataset** — read it via
+`api.datasets.createUserSearch` + `api.datasets.search` with
+dataset type `'action_log'` — **singular**; the plural
+`action_logs` is the SQL *table* name (`executeSql`) and 422s as
+a dataset type. Base SQL alias: `ral`. Rows exist only for
+**live** mode — dry runs never write here.
+
+## 1. When a row appears (the scheduled gap)
+
+Not all at once. Two moments:
+
+```
+   at run time          — failed / filtered / skipped outcomes
+                          land immediately
+   at execution time    — a scheduled action gets its row only
+                          when the trigger clock fires and it
+                          actually executes
+```
+
+Between those two moments a scheduled send is INVISIBLE here: its
+execution log exists (the platform accepted it), but no
+action_log row and no message row yet. A UI that only reads the
+datalake shows nothing and looks broken — read the execution logs
+(`workflows.md` §6) and say "scheduled — nothing sent yet".
+
+## 2. Fields
+
+```
+id, workflow_id, action_id, workflow_execution_log_id,
+batch_id            — the run this outcome belongs to; THE
+                      campaign key (messages does not have it)
+decision_key        — which action fired
+mdm_subject_id, subject_name, session_id
+action_type ('sms'|'email'|'voice'|'data_exchange'), channel,
+classification
+status              — see §3
+external_id         — provider id; joins to messages.external_id
+sent_at, tool_call_payload, idempotency_key, metadata,
+attachments, body, sender_tool_id
+```
+
+## 3. Statuses
+
+```
+   pending → queued → sent → delivered
+                        └──→ failed
+
+   skipped    — the action's runtime_filter said no; nothing sent
+   filtered   — the parent run was filtered out; nothing sent
+   cancelled  — manually cancelled
+```
+
+Initial status mirrors the action execution log's outcome; a
+status updater with an `action_log_config` can move
+`sent → delivered/failed` here too (optional — many setups only
+reconcile messages).
+
+## 4. How everything joins
+
+```
+   run (batch_id) ──── WorkflowRunLog          "how is the batch doing"
+        │
+        ├── WorkflowExecutionLog (per subject) "what did the pipeline decide"
+        │        │
+        │        └── ActionExecutionLog        "what did each action attempt"
+        │                 │  (live + actually executed)
+        │                 ▼
+        └────────── action_logs row            "the outcome, queryable"
+                          │ external_id
+                          ▼
+                    messages row               "the communication + delivery"
+```
+
+Left side lives in the platform DB (read via
+`api.workflows.batchLogs` / `api.workflows.workflowLogs`); the
+bottom two are datalake datasets. `batch_id` ties the datalake
+rows back to the run; `external_id` ties an action_log to its
+message.
+
+## 5. Reading + audience export
+
+```typescript
+// dataset type is SINGULAR 'action_log' (the table is plural)
+const { data: search } = await api.datasets.createUserSearch(
+  tenantSlug, datalakeSlug, 'action_log',
+  { search_query: `ral.batch_id = '${batchId}'` },
+)
+const { data: page } = await api.datasets.search(
+  tenantSlug, datalakeSlug, 'action_log',
+  { userSearchId: search.id, dataAccessMode: 'unregulated' },
+)
+```
+
+Filterable columns (Flop): `status`, `batch_id`, `action_type`,
+`channel`, `classification`, `workflow_id`, `sent_at`,
+`external_id`, `mdm_subject_id`, `inserted_at`.
+
+"Who did this campaign go to" = the query above (subject columns
++ status per row — exportable as-is). For bulk export the platform
+also merges each finished batch into NDJSON artifacts in cold
+storage:
+
+```
+   <datalake>/workflows/<wf_slug>/<batch_id>/merged.ndjson              (per-subject)
+   <datalake>/workflows/<wf_slug>/<batch_id>/<decision_key>/merged.ndjson  (per-action payloads)
+```
+
+The batch log row (`api.workflows.batchLogs.get`) carries the
+download references once the batch completes.
+
+## 6. Gotchas
+
+1. **The scheduled gap (§1).** No action_log row ≠ nothing
+   happened. Check the execution logs before declaring a run
+   empty.
+
+2. **`batch_id` is a string, not a UUID** — manual runs look like
+   `manual:<uuid>`; DAC-triggered runs carry the ingest batch id.
+   Compare as strings.
+
+3. **One subject can have many rows for the same decision.**
+   Re-fires via `workflows.execute` with `manual_override: true`
+   (the retry path) create a NEW action_log each time. Latest row
+   wins for "current state"; the full set is the audit trail.
+
+4. **`skipped`/`filtered` rows are successes of the control
+   system, not failures.** Only `failed` is the retry surface
+   (`workflows.md` §8).
+
+5. **`tool_call_payload` is the rendered call** — what was
+   actually sent to the tool, after Liquid. When a message looks
+   wrong, read this before blaming the template engine.

package/.agent/action_status_updaters.md

@@ -204,11 +204,12 @@ branch.
 ### Read shapes
 
 ```
-.list(tenantSlug, datalakeSlug)              Paged: { data, meta }
-.get(tenantSlug, datalakeSlug, idOrSlug)     One row
+.list(tenantSlug, datalakeSlug, query?)      Paged: { data, meta }
+                                              (full Flop query — type_naming.md)
+.get(tenantSlug, datalakeSlug, id)           One row — UUID only
 .metadata(tenantSlug, datalakeSlug)          Markdown — catalog
 .metadataDetails(tenantSlug, datalakeSlug,   Markdown — one updater
-                  idOrSlug)
+                  id)                         (UUID only)
 ```
 
 ### Update
@@ -262,3 +263,35 @@ check or retry for partial-delete states.
    transient delivery delays don't fall between two polls.
    The defaults in the wire-shape example illustrate this
    pattern: 30-minute cron, 45-minute window.
+
+## 7. Where delivery truth comes from (consumer view)
+
+If you only READ the platform (an operator UI, a dashboard), this
+is the part that matters:
+
+```
+   dispatch writes:            messages row, status 'sent',
+                               external_id = provider's id
+   THIS updater writes:        'delivered'  or  'failed' +
+                               failure_reason (+ delivered_at)
+   nothing else writes those.
+```
+
+- **No updater configured → no delivery truth.** Rows stay `sent`
+  forever; a delivery-rate number computed from them is fiction.
+  Updaters are created manually (this page §1) — the platform does
+  not auto-create them per sender tool.
+- **The join is `{external_id, set_params}`,** exact-match, silent
+  on misses (gotcha 3). "Eventually honest": a just-sent row is
+  neither delivered nor failed yet — show the in-between state.
+- **Retry is not here.** The updater only reports. Re-sending a
+  failed message is `workflows.execute` for that subject +
+  decision (`mode: 'live'`, `manual_override: true`) — the same
+  call as any manual dispatch; there is no retry endpoint. See
+  `workflows.md` §8.
+- **Engagement is not here either.** `opened_at` /
+  `form_submitted_at` arrive via
+  `connectedApps.updateMessageTracking` (magic-link seam,
+  `connected_apps.md` §6) and never touch `status`.
+- Field-by-field semantics of the rows being updated:
+  `messages.md`, `action_logs.md`.

package/.agent/ai_agents.md

@@ -331,7 +331,8 @@ once `enabled: true`.
 ### Read shapes
 
 ```
-.list(tenantSlug, datalakeSlug)              Paged: { data, meta }
+.list(tenantSlug, datalakeSlug, query?)      Paged: { data, meta }
+                                              (full Flop query — type_naming.md)
 .get(tenantSlug, datalakeSlug, id)           One row, BY ID (UUID — not slug)
 .metadata(tenantSlug, datalakeSlug)          Markdown catalog
 .metadataDetails(tenantSlug, datalakeSlug,   Markdown for one agent;

package/.agent/connected_apps.md

@@ -27,6 +27,15 @@ The namespace splits into **two roles**:
   machine-to-machine API key) when a customer hits a magic link. Uses the app's
   `slug` as the path key.
 
+**Connected apps are single-tenant, full stop.** A connected app
+belongs to exactly ONE tenant (and one datalake under it): its
+auto-provisioned M2M key is tenant-scoped, its magic links resolve
+against that tenant's data, and its publishable browser key carries
+that tenant's origin allowlist. Do NOT design a connected app that
+serves multiple tenants from one deployment — per tenant, register
+a separate connected app (separate keys, separate routes). There is
+no cross-tenant resolution path, by construction.
+
 Connected apps are **Datalake-DB-resident** — the parent datalake
 must be `status: 'ready'` before you `create()`.
 
@@ -219,7 +228,8 @@ and can be retried via `.syncRoutes`.
 ### Read shapes — management
 
 ```
-.list(tenantSlug, datalakeSlug)              Paged: { data, meta }
+.list(tenantSlug, datalakeSlug, query?)      Paged: { data, meta }
+                                              (full Flop query — type_naming.md)
 .get(tenantSlug, datalakeSlug, id)           One row, by UUID
 .metadata(tenantSlug, datalakeSlug)          Markdown catalog
 .metadataDetails(tenantSlug, datalakeSlug,   Markdown for one app
@@ -343,7 +353,16 @@ await api.connectedApps.updateMessageTracking(
 
 Both calls are authenticated with the connected app's
 auto-provisioned machine-to-machine API key (typically configured as
-`ALVERA_API_KEY` in the deployment environment).
+`ALVERA_API_KEY` in the deployment environment). Both are also on
+the `public_api` (publishable-key) allowlist — alongside `ingest`,
+`ingest-file`, and `mdm/verify` — so a browser-side app holding
+only a publishable key can call them.
+
+**This is the engagement seam.** `updateMessageTracking` writes
+`opened_at` / `form_submitted_at` onto the message row — the
+open/click/conversion half of campaign analytics — and it NEVER
+changes `status` (delivery truth belongs to the action status
+updater; see `messages.md` §1 for who writes which field).
 
 ### Workflow-side wiring
 

package/.agent/cookbook/_setup/accounts_receivable.md

@@ -36,13 +36,15 @@ having to copy-paste this prelude.
 ## 001 — root admin signs in and provisions a fresh industry-admin user
 
 Authenticate as the platform's root admin (`admin@dev.local` /
-`devpassword` in local dev). Then sign up a per-run industry-admin
+`devpassword` in local dev) via the tenantless bootstrap login —
+keyless by structural necessity (no tenant exists yet to scope a
+key to), and a dev/test-only surface. Then sign up a per-run industry-admin
 user (`sarah`) under a unique email derived from `runSuffix`, and
 confirm them so they can sign in. Both the signup and the confirm
 endpoints require root scope.
 
 ```typescript
-ctx.rootSession = await createSession({
+ctx.rootSession = await createBootstrapSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: process.env.ALVERA_ROOT_EMAIL!,
   password: process.env.ALVERA_ROOT_PASSWORD!,
@@ -50,12 +52,13 @@ ctx.rootSession = await createSession({
 ctx.rootApi = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: ctx.rootSession.sessionToken,
+  apiKey: '',
 })
 
 ctx.sarahEmail = `cookbook-sarah-${runSuffix}@dev.local`
 ctx.sarahPassword = 'CookbookPass1!'
 
-const signUpResp = await ctx.rootApi.auth.signUp({
+const signUpResp = await ctx.rootApi.admin.signUp({
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
   first_name: 'Cookbook',
@@ -74,7 +77,7 @@ captured into the closure-scoped `tenantSlug` slot for downstream
 steps.
 
 ```typescript
-ctx.sarahTenantlessSession = await createSession({
+ctx.sarahTenantlessSession = await createBootstrapSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
@@ -82,6 +85,7 @@ ctx.sarahTenantlessSession = await createSession({
 ctx.sarahTenantlessApi = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: ctx.sarahTenantlessSession.sessionToken,
+  apiKey: '',
 })
 
 const tenantResp = await ctx.sarahTenantlessApi.tenants.create({
@@ -98,15 +102,28 @@ is assigned to the closure-scoped `api` slot so the scenario
 cookbook's steps inherit it via inlining.
 
 ```typescript
+// A tenant-scoped login requires X-API-Key — mint a public_api key for
+// the fresh tenant via the platform-admin side door (root Bearer). In the
+// web console this is Settings -> API Keys; any of the tenant's keys
+// satisfies the login gate, and the minted Bearer inherits this key's
+// origin policy.
+const { data: mintedKey } = await ctx.rootApi.admin.createTenantApiKey(tenantSlug, {
+  name: `Cookbook Bootstrap Key ${runSuffix}`,
+  data_access_mode: 'unregulated',
+})
+ctx.tenantApiKey = mintedKey.api_key
+
 const sarahTenantSession = await createSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
   tenantSlug,
+  apiKey: ctx.tenantApiKey,
 })
 api = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: sarahTenantSession.sessionToken,
+  apiKey: ctx.tenantApiKey,
 })
 ```
 
@@ -266,6 +283,9 @@ After this setup runs, the closure-scoped slots are populated as:
 - `ctx.sarahEmail` / `ctx.sarahPassword` — the per-run admin
   credentials (kept on `ctx` because no scenario cookbook needs
   to re-authenticate by default)
+- `ctx.tenantApiKey` — the tenant's publishable API key (minted in
+  setup via `admin.createTenantApiKey`); thread it into any
+  additional tenant-scoped `createSession` a scenario performs
 
 Scenario cookbooks under `industry: accounts_receivable` start at
 their own `§001` with these slots already populated.

package/.agent/cookbook/_setup/foundation.md

@@ -35,13 +35,15 @@ having to copy-paste this prelude.
 ## 001 — root admin signs in and provisions a fresh industry-admin user
 
 Authenticate as the platform's root admin (`admin@dev.local` /
-`devpassword` in local dev). Then sign up a per-run industry-admin
+`devpassword` in local dev) via the tenantless bootstrap login —
+keyless by structural necessity (no tenant exists yet to scope a
+key to), and a dev/test-only surface. Then sign up a per-run industry-admin
 user (`sarah`) under a unique email derived from `runSuffix`, and
 confirm them so they can sign in. Both the signup and the confirm
 endpoints require root scope.
 
 ```typescript
-ctx.rootSession = await createSession({
+ctx.rootSession = await createBootstrapSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: process.env.ALVERA_ROOT_EMAIL!,
   password: process.env.ALVERA_ROOT_PASSWORD!,
@@ -49,12 +51,13 @@ ctx.rootSession = await createSession({
 ctx.rootApi = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: ctx.rootSession.sessionToken,
+  apiKey: '',
 })
 
 ctx.sarahEmail = `cookbook-sarah-${runSuffix}@dev.local`
 ctx.sarahPassword = 'CookbookPass1!'
 
-const signUpResp = await ctx.rootApi.auth.signUp({
+const signUpResp = await ctx.rootApi.admin.signUp({
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
   first_name: 'Cookbook',
@@ -72,7 +75,7 @@ foundation tenant. The tenant's server-derived `slug` is captured
 into the closure-scoped `tenantSlug` slot for downstream steps.
 
 ```typescript
-ctx.sarahTenantlessSession = await createSession({
+ctx.sarahTenantlessSession = await createBootstrapSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
@@ -80,6 +83,7 @@ ctx.sarahTenantlessSession = await createSession({
 ctx.sarahTenantlessApi = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: ctx.sarahTenantlessSession.sessionToken,
+  apiKey: '',
 })
 
 const tenantResp = await ctx.sarahTenantlessApi.tenants.create({
@@ -96,15 +100,28 @@ is assigned to the closure-scoped `api` slot so the scenario
 cookbook's steps inherit it via inlining.
 
 ```typescript
+// A tenant-scoped login requires X-API-Key — mint a public_api key for
+// the fresh tenant via the platform-admin side door (root Bearer). In the
+// web console this is Settings -> API Keys; any of the tenant's keys
+// satisfies the login gate, and the minted Bearer inherits this key's
+// origin policy.
+const { data: mintedKey } = await ctx.rootApi.admin.createTenantApiKey(tenantSlug, {
+  name: `Cookbook Bootstrap Key ${runSuffix}`,
+  data_access_mode: 'unregulated',
+})
+ctx.tenantApiKey = mintedKey.api_key
+
 const sarahTenantSession = await createSession({
   baseUrl: process.env.ALVERA_BASE_URL!,
   email: ctx.sarahEmail,
   password: ctx.sarahPassword,
   tenantSlug,
+  apiKey: ctx.tenantApiKey,
 })
 api = createIsolatedPlatformApi({
   baseUrl: process.env.ALVERA_BASE_URL!,
   sessionToken: sarahTenantSession.sessionToken,
+  apiKey: ctx.tenantApiKey,
 })
 ```
 
@@ -262,6 +279,9 @@ After this setup runs, the closure-scoped slots are populated as:
 - `ctx.sarahEmail` / `ctx.sarahPassword` — the per-run admin
   credentials (kept on `ctx` because no scenario cookbook needs
   to re-authenticate by default)
+- `ctx.tenantApiKey` — the tenant's publishable API key (minted in
+  setup via `admin.createTenantApiKey`); thread it into any
+  additional tenant-scoped `createSession` a scenario performs
 
 Scenario cookbooks under `industry: foundation` start at their own
 `§001` with these slots already populated.