@hotmeshio/long-tail 0.23.2 → 0.24.1

package/docs/api/http/agents.md

@@ -2,7 +2,9 @@
 
 CRUD operations for agent automations — autonomous personas that react to events and run workflows on schedules. Each automation has an identity, motivation (goals/rules), event subscriptions, cron schedules, and a knowledge domain.
 
-All endpoints require authentication.
+All endpoints require authentication. Creating, updating, and deleting agents and subscriptions require builder access (superadmin or the `engineer` role).
+
+Configuring an agent or subscription also requires that the caller may act as the identity it runs as (its `execute_as`, else the agent's `user_id`). The act-as rule: a superadmin may act as anyone, and a caller holding an `admin`-type grant may act as an account that holds no superadmin grant and whose every role the caller holds at the same or higher type. A schedule or subscription with no identity runs as lt-system, and a `capability` subscription calls a tool with lt-system authority; only a superadmin may configure either.
 
 ## List agent automations
 
@@ -64,6 +66,8 @@ Returns an agent with aggregated stats (knowledge entry count, escalation count)
 POST /api/agents
 ```
 
+**Auth:** Requires builder access and the act-as rule for `user_id` and each schedule's identity.
+
 **Body:**
 
 ```json
@@ -101,6 +105,8 @@ POST /api/agents
 PUT /api/agents/:id
 ```
 
+**Auth:** Same as create.
+
 Partial update — only include fields to change. Changing `status` or `behaviors` automatically restarts event subscriptions and cron schedules.
 
 **Response 200:** The updated agent.
@@ -111,6 +117,8 @@ Partial update — only include fields to change. Changing `status` or `behavior
 DELETE /api/agents/:id
 ```
 
+**Auth:** Requires builder access.
+
 Permanently removes the agent. Event subscriptions are cascade-deleted. Cron schedules are stopped. Knowledge entries and workflow history are preserved.
 
 **Response 200:** `{ "deleted": true }`
@@ -153,6 +161,8 @@ GET /api/agents/:agentId/subscriptions
 POST /api/agents/:agentId/subscriptions
 ```
 
+**Auth:** Requires builder access and the act-as rule for the subscription's identity. A `capability` subscription requires superadmin.
+
 **Body:**
 
 ```json
@@ -188,6 +198,8 @@ POST /api/agents/:agentId/subscriptions
 PUT /api/agents/:agentId/subscriptions/:subId
 ```
 
+**Auth:** Same as create. Returns `404` when the subscription does not belong to the agent.
+
 Partial update.
 
 **Response 200:** The updated subscription.
@@ -198,4 +210,6 @@ Partial update.
 DELETE /api/agents/:agentId/subscriptions/:subId
 ```
 
+**Auth:** Requires builder access.
+
 **Response 200:** `{ "deleted": true }`

package/docs/api/http/escalations.md

@@ -24,7 +24,7 @@ A role is a task queue with four verbs — **search** (list/get), **claim**, **a
 
 - `read_scope` governs which escalations a member **sees** — list, `/available`, get-by-id, find-by-metadata, and stats. `self` means escalations assigned to the member (`assigned_to = user`); `all` means the whole role queue.
 - `write_scope` governs which escalations a member may **act on** — claim, resolve, cancel. `self` means only items already assigned to them; `none` is read-only.
-- Releasing and escalating are queue-management verbs and require `write_scope=all`. Creating a standalone escalation (`POST /api/escalations`) requires `write_scope=all` or global escalation access.
+- Releasing, escalating and assigning by query are queue-management verbs and require `write_scope=all`. Creating a standalone escalation (`POST /api/escalations`) requires `write_scope=all` or global escalation access.
 
 Defaults are `read_scope=all` and `write_scope=all` — the full-queue worker — so a plain `member` works the whole queue. See [Work-Surface Scope](roles.md#work-surface-scope) in the Roles API for the five member profiles and the **write ⊆ read** constraint.
 
@@ -649,7 +649,7 @@ Assign multiple escalations to a specific user, by id-set or by query (exactly o
 
 **Rows under a live claim are skipped** by a plain assign and counted in the response's `skipped` — assignment is claim-on-behalf, and an active claim wins. To take over live claims, pass `reassign: true` (ids form; admin/superadmin only): the takeover is one guarded statement, the displaced holder's in-flight resolve fails its claim assertion, and each taken row's `claimed` event carries `reassigned_from`.
 
-The query form is one atomic statement: selection and claim happen in the same UPDATE, so a row that re-parks between a search and an ids-assign is still captured. Use it whenever the population is describable by role + facets.
+The query form is one atomic statement: selection and claim happen in the same UPDATE, so a row that re-parks between a search and an ids-assign is still captured. Use it whenever the population is describable by role + facets. A member may use the query form only with `write_scope=all` on the queried role; the target user must hold that role.
 
 **Request body:**
 
@@ -830,7 +830,7 @@ Reassign a single escalation to a different role. The caller must be authorized
 GET /api/escalations/by-workflow/:workflowId
 ```
 
-Returns all escalations linked to a specific workflow ID.
+Returns the escalations linked to a specific workflow ID that the caller may read: every escalation for callers with global escalation access, escalations in roles the caller reads at `all` scope, and, for roles held at `self` read scope, only those assigned to the caller.
 
 **Path parameters:**
 

package/docs/api/http/exports.md

@@ -1,6 +1,8 @@
 # Exports API
 
-Export endpoints expose workflow state and execution history. The execution history endpoint produces structured, typed events — useful for debugging, auditing, and migrating data. All endpoints require authentication.
+Export endpoints expose workflow state and execution history. The execution history endpoint produces structured, typed events — useful for debugging, auditing, and migrating data.
+
+**Auth:** Every endpoint requires builder access (superadmin or the `engineer` role), except `GET /api/workflow-states/:workflowId/execution`. That endpoint is open to builders and to the person who started the run or the account it runs as (read from the run's start envelope: `lt.userId`, or `lt.initiatedBy` when it runs under `execute_as`); others receive `403`.
 
 Every endpoint resolves the workflow automatically from the `workflowId` — no additional parameters needed.
 

package/docs/api/http/file-browser.md

@@ -1,6 +1,8 @@
 # File Browser API
 
-Browse, preview, download, share, and delete files in the storage backend (S3, MinIO, or local filesystem). All endpoints require authentication except file serving.
+Browse, preview, download, share, and delete files in the storage backend (S3, MinIO, or local filesystem).
+
+**Auth:** Every `/api/file-browser` endpoint (browse, metadata, signed-url, delete, download, upload) requires builder access (superadmin or the `engineer` role). Serving a file at `/api/files/{filePath}` requires the signed token from a signed URL (`?token=`).
 
 ## Browse files
 

package/docs/api/http/mcp-endpoint.md

@@ -75,7 +75,7 @@ Connect Claude Code to your Long Tail instance as an MCP server. Once connected,
 
 ### Step 1: Get an API key
 
-Start Long Tail (`docker compose up -d --build`). The startup log shows two seeded API keys:
+Start Long Tail (`docker compose up -d --build`). On first start, docker compose sets `LT_SEED_SERVICE_KEYS=true`, so the container's stdout shows two seeded API keys:
 
 ```
 [seed-mcp] read key: lt_bot_<read-key>
@@ -139,13 +139,16 @@ Claude Code calls `get_system_overview` — one call returns triage, throughput,
 
 ## Authentication
 
-Two token types are supported:
+The credential travels in the `Authorization: Bearer` header. The host's session cookie does not authenticate `/mcp`. Three token types are supported:
 
 | Type | Format | Use case |
 |------|--------|----------|
-| JWT | Standard Bearer token from `POST /api/auth/login` | Interactive sessions, testing |
+| OAuth access token | Issued by the Long Tail OAuth server for this resource (when the OAuth server is enabled) | MCP clients that sign in a person |
+| JWT | Signed user token, such as the one from `POST /api/auth/login` | Interactive sessions, testing |
 | API key | `lt_bot_*` prefix | Service accounts, automation |
 
+When the OAuth server is enabled, a `401` response carries a `WWW-Authenticate: Bearer resource_metadata="..."` challenge so MCP clients can discover how to sign in. An access token authenticates only while its grant is live.
+
 ### Service Account Setup
 
 1. Create a service account: `POST /api/bot-accounts`
@@ -165,11 +168,11 @@ A read key cannot invoke write operations (create, update, delete, invoke workfl
 
 ### Seeded Service Account
 
-Long Tail seeds an `mcp-service` account at startup with two pre-configured API keys:
+Long Tail seeds an `mcp-service` account at startup with two API keys:
 - **read** — scopes: `["mcp:read"]`
 - **full** — scopes: `["mcp:read", "mcp:full"]`
 
-Keys are logged once at startup and cannot be retrieved again. For production, create a new service account and generate keys via the dashboard or API.
+With `LT_SEED_SERVICE_KEYS=true` (local docker compose), the keys are minted at first start and printed once to stdout, never through the logger; they cannot be retrieved again. Without it, the account is created with no keys, and a superadmin mints them from the dashboard or the bot-accounts API.
 
 ## Exposure Control
 

package/docs/api/http/mcp-servers.md

@@ -1,6 +1,8 @@
 # MCP Servers API
 
-Manage MCP server registrations, connections, and tool invocations. All endpoints require authentication.
+Manage MCP server registrations, connections, and tool invocations. All endpoints require authentication. Registering, testing, updating, deleting, connecting, and disconnecting servers require builder access (superadmin or the `engineer` role).
+
+A `stdio` server is a command Long Tail starts on its own host, with that host's environment and network. Builder access therefore includes running commands on the host: grant the `engineer` role with the same care as host access.
 
 ## List servers
 
@@ -8,6 +10,8 @@ Manage MCP server registrations, connections, and tool invocations. All endpoint
 GET /api/mcp/servers
 ```
 
+`transport_config` is included only for builders.
+
 **Query parameters:**
 
 | Parameter | Type | Description |
@@ -53,6 +57,8 @@ GET /api/mcp/servers
 POST /api/mcp/servers
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 **Request body:**
 
 | Field | Type | Required | Description |
@@ -76,15 +82,17 @@ POST /api/mcp/servers
 **Transport config for `sse`:**
 
 ```json
-{ "url": "http://localhost:3001/sse" }
+{ "url": "http://localhost:3001/sse", "headers": { "Authorization": "Bearer <token>" } }
 ```
 
 **Transport config for `streamable-http`:**
 
 ```json
-{ "url": "http://localhost:3001/mcp" }
+{ "url": "http://localhost:3001/mcp", "headers": { "Authorization": "Bearer <token>" } }
 ```
 
+`headers` is optional and is sent with every request to the server, the SSE stream included. Like the rest of `transport_config`, it is returned only to builders.
+
 **Response 201:** Created server record.
 
 **Response 409:** Server name already exists.
@@ -95,6 +103,8 @@ POST /api/mcp/servers
 GET /api/mcp/servers/:id
 ```
 
+`transport_config` is included only for builders.
+
 **Response 200:** Server record.
 
 **Response 404:** Server not found.
@@ -105,6 +115,8 @@ GET /api/mcp/servers/:id
 PUT /api/mcp/servers/:id
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 **Request body:** Any fields from the registration (partial update), including `tags`, `compile_hints`, and `credential_providers`.
 
 **Response 200:** Updated server record.
@@ -117,6 +129,8 @@ PUT /api/mcp/servers/:id
 DELETE /api/mcp/servers/:id
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 **Response 200:**
 
 ```json
@@ -131,6 +145,8 @@ DELETE /api/mcp/servers/:id
 POST /api/mcp/servers/test-connection
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 Test connectivity to an MCP server without persisting a registration. Creates a temporary client, connects, lists tools, then disconnects.
 
 **Request body:**
@@ -167,6 +183,8 @@ On failure:
 POST /api/mcp/servers/:id/connect
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 Establishes a connection to the registered MCP server and caches its tool manifest.
 
 **Response 200:**
@@ -181,6 +199,8 @@ Establishes a connection to the registered MCP server and caches its tool manife
 POST /api/mcp/servers/:id/disconnect
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 **Response 200:**
 
 ```json
@@ -222,16 +242,24 @@ POST /api/mcp/servers/:id/tools/:toolName/call
 
 Invoke a tool on a connected MCP server.
 
+**Auth:** The tool runs as the caller, or as the `execute_as` account when given. A built-in tool requires the capability its manifest `gate` declares, checked for the acting account; a built-in tool with no gate requires builder access. A tool on an external server (any registered network or local-process server) requires builder access, since it runs on the credential stored with that server. `execute_as` follows the act-as rule: a superadmin may act as anyone, and a caller holding an `admin`-type grant may act as an account that holds no superadmin grant and whose every role the caller holds at the same or higher type.
+
 **Request body:**
 
 ```json
 {
   "arguments": {
     "image_url": "https://example.com/image.png"
-  }
+  },
+  "execute_as": "optional-account-id"
 }
 ```
 
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `arguments` | `object` | No | Tool arguments |
+| `execute_as` | `string` | No | Account id or `external_id` to run the tool as |
+
 **Response 200:**
 
 ```json
@@ -242,6 +270,8 @@ Invoke a tool on a connected MCP server.
 }
 ```
 
+**Response 403:** The caller may not act as `execute_as`, or the acting account lacks the tool's capability.
+
 **Response 422** (missing credential):
 
 ```json

package/docs/api/http/namespaces.md

@@ -33,6 +33,8 @@ GET /api/namespaces
 POST /api/namespaces
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 Creates or upserts a namespace. Typically called automatically during YAML workflow deployment.
 
 **Request body:**

package/docs/api/http/pipelines.md

@@ -114,6 +114,8 @@ Returns full execution detail for a specific run, including inflated activity ev
 POST /api/pipelines/:jobId/interrupt
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 Immediately terminates a running pipeline job via `HotMesh.interrupt()`. The job is marked as interrupted and its state is expired.
 
 **Body:**

package/docs/api/http/roles.md

@@ -71,10 +71,11 @@ Certain API endpoints require builder access (`superadmin` or `engineer` role):
 
 | Endpoint | Access |
 |----------|--------|
-| `POST/PUT/DELETE /api/users` | Builder |
-| `POST /api/users/:id/roles` | Admin (scoped — see below) |
+| `POST/PUT/PATCH/DELETE /api/users` | Builder |
+| `POST /api/users/:id/roles` | Admin (scoped, see below) |
+| `DELETE /api/users/:id/roles/:role` | Admin (scoped, see below) |
 | All `/api/bot-accounts` | Builder |
-| All `/api/roles` mutations | Builder |
+| All `/api/roles` mutations | Admin access or the `engineer` role |
 | All `/api/controlplane` | Builder |
 
 ### Scoped Role Assignment
@@ -87,6 +88,8 @@ When assigning roles via `POST /api/users/:id/roles`, the caller's own roles det
 | `engineer` | Any role up to `admin` type (never `superadmin` type) |
 | `*/admin` (non-builder) | `member` or `admin` type for roles they themselves hold |
 
+Removing a role follows the same rule for the role at the type the account holds it. Only a superadmin may change, remove roles from, or mint keys for an account that holds a superadmin grant; others receive `403`.
+
 A caller who may assign a role may set any work-surface scope (`read_scope`/`write_scope`) on it. Scope is a refinement of a `member` grant; it is ignored for `admin`/`superadmin`, which always act on the whole queue.
 
 ## List roles for a user
@@ -289,7 +292,7 @@ Returns all roles with metadata and usage counts.
 POST /api/roles
 ```
 
-Create a standalone role. Requires admin.
+Create a standalone role. Requires role manager (admin type, superadmin, or engineer).
 
 **Request body:**
 
@@ -325,7 +328,7 @@ Create a standalone role. Requires admin.
 DELETE /api/roles/:role
 ```
 
-Delete a role if it has no references. Requires admin.
+Delete a role if it has no references. Requires role manager (admin type, superadmin, or engineer).
 
 **Path parameters:**
 
@@ -494,7 +497,7 @@ Returns all escalation chain pairs.
 POST /api/roles/escalation-chains
 ```
 
-Add a single escalation chain entry. Requires admin.
+Add a single escalation chain entry. Requires role manager (admin type, superadmin, or engineer).
 
 **Request body:**
 
@@ -527,7 +530,7 @@ Add a single escalation chain entry. Requires admin.
 DELETE /api/roles/escalation-chains
 ```
 
-Remove a single escalation chain entry. Requires admin.
+Remove a single escalation chain entry. Requires role manager (admin type, superadmin, or engineer).
 
 **Request body:**
 
@@ -576,7 +579,7 @@ Returns the allowed escalation targets for a specific role.
 PUT /api/roles/:role/escalation-targets
 ```
 
-Replace all escalation targets for a role. Requires admin.
+Replace all escalation targets for a role. Requires role manager (admin type, superadmin, or engineer).
 
 **Path parameters:**
 

package/docs/api/http/service-accounts.md

@@ -1,6 +1,6 @@
 # Service Accounts API
 
-Service accounts are named identities that authenticate with API keys instead of passwords. They share the same role-based access control as human users. All endpoints require admin access.
+Service accounts are named identities that authenticate with API keys instead of passwords. They share the same role-based access control as human users. All endpoints require builder access (superadmin or the `engineer` role). Role assignments follow the [scoped role assignment](roles.md#scoped-role-assignment) rules, and only a superadmin may change, delete, assign or remove roles on, or create or revoke keys for an account that holds a superadmin grant.
 
 ## List service accounts
 
@@ -107,7 +107,7 @@ Deletes the service account and all its API keys (cascade).
 
 ## Service account roles
 
-Roles work identically to user roles.
+Roles work identically to user roles, including the [scoped role assignment](roles.md#scoped-role-assignment) rules.
 
 ```
 GET    /api/bot-accounts/:id/roles
@@ -191,6 +191,12 @@ DELETE /api/bot-accounts/:id/api-keys/:keyId
 { "revoked": true }
 ```
 
+**Response 404:** The key does not exist or belongs to a different service account than `:id`.
+
+```json
+{ "error": "API key not found" }
+```
+
 ## Using a service account API key
 
 Include the raw key as a Bearer token in any API request:

package/docs/api/http/settings.md

@@ -21,7 +21,7 @@ GET /api/settings
   "events": {
     "transport": "socketio",
     "natsWsUrl": null,
-    "natsToken": null
+    "reconnect": { "initialDelayMs": 1000, "maxDelayMs": 60000, "noticeAfterMs": 30000, "spreadMs": 5000 }
   },
   "auth": {
     "sso": false,
@@ -42,8 +42,35 @@ GET /api/settings
 | `escalation.claimDurations` | `number[]` | Available claim duration options in minutes. Used by the frontend to populate duration selectors. Configurable via the `LT_CLAIM_DURATION_OPTIONS` environment variable (JSON array). |
 | `events.transport` | `'socketio' \| 'nats' \| 'none'` | Dashboard event transport. Defaults to `socketio`. Reports `nats` only when `EVENT_TRANSPORT=nats` is set and a NATS adapter is registered. |
 | `events.natsWsUrl` | `string \| null` | NATS WebSocket URL for browser connections. Only present when a NATS adapter is registered. Read from `NATS_WS_URL`. |
-| `events.natsToken` | `string \| null` | NATS auth token for browser connections. Only present when a NATS adapter is registered. Read from `NATS_TOKEN`. |
+| `events.reconnect.initialDelayMs` | `number` | First delay before the dashboard retries a dropped event connection. Read from `NATS_RECONNECT_INITIAL_MS` (default `1000`). |
+| `events.reconnect.maxDelayMs` | `number` | Upper bound on the retry delay as it backs off. Read from `NATS_RECONNECT_MAX_MS` (default `60000`). |
+| `events.reconnect.noticeAfterMs` | `number` | How long the connection may stay down before the dashboard shows a notice. Read from `NATS_LIVE_NOTICE_AFTER_MS` (default `30000`). |
+| `events.reconnect.spreadMs` | `number` | Window the first retry after a drop, and the catch-up refetch after reconnecting, are spread across, so tabs return gradually after a deploy. Read from `NATS_RECONNECT_SPREAD_MS` (default `5000`). |
 | `auth.sso` | `boolean` | Whether SSO is configured for embedded deployments. When `true`, the dashboard auto-exchanges host auth for an LT JWT instead of showing the login form. |
 | `auth.ssoLogoutUrl` | `string \| null` | URL to redirect the browser on logout. Set by the host via `sso.logoutUrl` in the startup config. When `null`, the dashboard shows its own login page on logout. |
 | `ai.enabled` | `boolean` | Whether an LLM API key is configured. When `false`, the dashboard hides AI-specific features (pipelines designer, AI assistant, triage). |
 | `branding.appName` | `string` | The product name shown in the dashboard header. Configured via `branding.appName` in the startup config; defaults to `"LongTail"`. |
+
+## Get NATS credentials
+
+```
+GET /api/nats-credentials
+```
+
+**Auth:** Requires authentication.
+
+Returns the connection details the dashboard uses to subscribe to NATS events.
+
+**Response 200:**
+
+```json
+{
+  "natsWsUrl": "wss://example.com/nats?ticket=...",
+  "natsToken": null
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `natsWsUrl` | `string \| null` | NATS WebSocket URL. Behind the WebSocket proxy, the URL carries a `ticket` query parameter for the caller, valid for `NATS_WS_TICKET_TTL_SECONDS` (default `300`). `null` when no NATS adapter is registered. |
+| `natsToken` | `string \| null` | `null` behind the WebSocket proxy, since the proxy holds the NATS credential and the ticket allows subscribing only. For direct connections, `NATS_DASHBOARD_TOKEN` when set, else `NATS_TOKEN`. |

package/docs/api/http/tasks.md

@@ -49,6 +49,8 @@ POST /api/tasks
 
 ---
 
+**Run data.** A task row carries its run's input (`envelope`), output (`data`) and `metadata`. A builder, and the person who started the run or the account it runs as, receive them; for any other caller those three fields are omitted from list, process and single-task responses.
+
 ## List tasks
 
 ```
@@ -169,7 +171,7 @@ List distinct `origin_id` values with summary stats. Each origin ID represents a
 GET /api/tasks/processes/:originId
 ```
 
-Returns all tasks and escalations for a process (identified by `origin_id`).
+Returns all tasks for a process (identified by `origin_id`), and the escalations in that process the caller may read (the same read-scope rule as `GET /api/escalations/by-workflow/:workflowId`).
 
 **Path parameters:**
 

package/docs/api/http/topics.md

@@ -2,7 +2,7 @@
 
 Browse, register, and manage the topic catalog — a persistent registry of known event topics with descriptions, payload schemas, and subscriber counts.
 
-All endpoints require authentication.
+All endpoints require authentication. Registering, updating, deleting, and publishing (`POST /api/topics/by-name/:topic/publish`) require builder access (superadmin or the `engineer` role). Publishing a subject that starts with `system.` or `agent.` requires superadmin.
 
 ## List topics
 
@@ -94,6 +94,8 @@ Subscribers are matched using NATS-style pattern matching — an agent subscribe
 POST /api/topics
 ```
 
+**Auth:** Requires builder access.
+
 Manually register a topic in the catalog. Use this to pre-declare topics before first publish.
 
 **Body:**
@@ -134,6 +136,8 @@ Manually register a topic in the catalog. Use this to pre-declare topics before
 PUT /api/topics/by-name/:topic
 ```
 
+**Auth:** Requires builder access.
+
 Partial update — only include fields to change. System topics (`source: 'system'`) can be updated (description, tags) but not deleted.
 
 **Body:**
@@ -155,6 +159,8 @@ Partial update — only include fields to change. System topics (`source: 'syste
 DELETE /api/topics/by-name/:topic
 ```
 
+**Auth:** Requires builder access.
+
 Permanently removes a topic from the catalog. System topics are protected.
 
 **Response 200:** `{ "deleted": true }`

package/docs/api/http/users.md

@@ -1,6 +1,6 @@
 # Users API
 
-Users represent the humans who claim and resolve escalations. Each user has a unique `external_id` that maps to your application's identity system. All endpoints require authentication. Mutating endpoints (create, update, delete, role management) require admin access (`admin` or `superadmin` role).
+Users represent the humans who claim and resolve escalations. Each user has a unique `external_id` that maps to your application's identity system. All endpoints require authentication. Creating, updating, patching, and deleting users require builder access (superadmin or the `engineer` role). Adding and removing roles require admin access and follow the assignment rules in the [Roles API](roles.md#scoped-role-assignment). Only a superadmin may grant the `superadmin` type or change a superadmin account.
 
 For service identities (CI bots, schedulers, automated agents), use the [Service Accounts API](service-accounts.md) instead. Service accounts share the same RBAC system but authenticate with API keys rather than passwords or OAuth.
 
@@ -76,6 +76,8 @@ GET /api/users/:id
 POST /api/users
 ```
 
+**Auth:** Requires builder access. Every initial role must be one the caller may assign (see [Roles API](roles.md#scoped-role-assignment)); otherwise `403`.
+
 **Request body:**
 
 | Field | Type | Required | Description |
@@ -140,6 +142,8 @@ Each element in `roles`:
 PUT /api/users/:id
 ```
 
+**Auth:** Requires builder access. Changing a superadmin account requires superadmin (`403` otherwise).
+
 Partial update — only the fields you include are changed.
 
 **Request body:**
@@ -174,7 +178,7 @@ Partial update — only the fields you include are changed.
 PATCH /api/users/:id/properties
 ```
 
-Atomically patch the user's properties dictionary (`metadata`) — one statement, never read-merge-write. Editing one property can never clobber another; a rename preserves its value with no key-absent window. Builder only (the same gate as every other user write).
+Atomically patch the user's properties dictionary (`metadata`) — one statement, never read-merge-write. Editing one property can never clobber another; a rename preserves its value with no key-absent window. Requires builder access, the same gate as every other user write. Changing a superadmin account requires superadmin.
 
 **Request body:**
 
@@ -226,6 +230,8 @@ The property keys the platform itself resolves identities against — every enab
 DELETE /api/users/:id
 ```
 
+**Auth:** Requires builder access. Changing a superadmin account requires superadmin (`403` otherwise).
+
 Deletes the user and all associated role assignments (cascade).
 
 **Response 200:**

package/docs/api/http/workflows.md

@@ -232,7 +232,7 @@ Start a workflow by its registered type. The workflow must have `invocable: true
 |-------|------|----------|-------------|
 | `data` | `object` | yes | Business data passed to the workflow as `envelope.data` |
 | `metadata` | `object` | no | Control flow metadata passed as `envelope.metadata` |
-| `execute_as` | `string` | no | Service account `external_id` to run as (admin only) |
+| `execute_as` | `string` | no | Account `external_id` or id to run as. Requires admin access and must satisfy the act-as rule below. |
 
 The input gate validates against the `metadata` in the request; the dashboard sends the config's `envelope_schema.metadata` with every invoke it starts.
 
@@ -268,12 +268,16 @@ The workflow starts on its configured `task_queue` with a generated workflow ID
 | `403` | `{ "error": "Workflow is not invocable" }` | `invocable` is `false` |
 | `403` | `{ "error": "User not registered" }` | RBAC check failed — no matching user |
 | `403` | `{ "error": "Insufficient role for invocation" }` | User lacks a required invocation role |
+| `403` | `{ "error": "execute_as may not exceed your own authority" }` | The caller may not act as the `execute_as` account |
+| `404` | `{ "error": "execute_as principal \"...\" not found" }` | No account matches `execute_as` |
 | `404` | `{ "error": "Workflow not found" }` | No config exists for this type |
 | `422` | `{ "error": "data failed input schema validation (n violations)", "code": "schema_validation", "violations": [{ "field", "message" }], "role": null, "schemaVersion": null, "workflowType" }` | The config declares `input_schema` and `data` violates it; `x-lt-options` over pinned `input_lookups` constrains values to the resolved edition |
 
 **Authorization:**
 
-When `invocation_roles` is empty, any authenticated user can invoke. When set, the user must hold at least one of the listed roles (checked against `lt_user_roles` via the user's `external_id`). Superadmins bypass this check.
+When `invocation_roles` is empty, any authenticated user can invoke. When set, the user must hold at least one of the listed roles. Roles are read from the caller's current grants in `lt_user_roles`, not from token claims. A superadmin grant, or the `admin` role held with `admin` type, invokes any workflow. `capabilityInvoke` requires a superadmin grant.
+
+`execute_as` follows the act-as rule: a superadmin may act as anyone. A caller holding an `admin`-type grant may act as an account that holds no superadmin grant and whose every role the caller holds at the same or higher type. Nobody else may.
 
 ### List the caller's invokable workflows
 
@@ -307,6 +311,8 @@ These endpoints let you check on running or completed workflows. The `workflowId
 GET /api/workflows/:workflowId/status
 ```
 
+**Auth:** Requires builder access (superadmin or the `engineer` role).
+
 **Response 200:**
 
 ```json
@@ -330,6 +336,8 @@ GET /api/workflows/:workflowId/result
 
 Returns the result if the workflow is complete, or `202` if it's still running. Never blocks.
 
+**Auth:** Requires builder access, or being the person who started the run or the account it runs as (read from the run's start envelope: `lt.userId`, or `lt.initiatedBy` when it runs under `execute_as`). Others receive `403`.
+
 **Response 200** (complete):
 
 ```json
@@ -361,6 +369,8 @@ Returns the result if the workflow is complete, or `202` if it's still running.
 
 ## Execution History Export
 
+Every `/api/workflow-states` endpoint requires builder access, except `/:workflowId/execution`, which follows the same rule as `GET /api/workflows/:workflowId/result`.
+
 Every workflow's full execution history is exportable in JSON. Two formats are available: a raw state export (HotMesh-native) and a structured execution event history with typed events, ISO timestamps, durations, and cross-references.
 
 Because workflows are durably executed — state is transactionally checkpointed to Postgres after every step — the export is a complete, faithful record of everything that happened. Every activity scheduled, every result returned, every signal received, every child workflow spawned. Nothing is reconstructed or approximated.
@@ -371,6 +381,8 @@ Because workflows are durably executed — state is transactionally checkpointed
 GET /api/workflows/:workflowId/export
 ```
 
+**Auth:** Requires builder access.
+
 Returns the raw workflow state from HotMesh. For full control over facet filtering and execution format, use the dedicated `/api/workflow-states` endpoints below.
 
 **Response 200:** Raw workflow state object (data, state, status, timeline, transitions).
@@ -658,6 +670,8 @@ POST /api/workflows/:workflowId/terminate
 
 Interrupt a running workflow. The workflow is immediately terminated.
 
+**Auth:** Requires builder access.
+
 **Path parameters:**
 
 | Parameter | Description |
@@ -688,16 +702,17 @@ Interrupt a running workflow. The workflow is immediately terminated.
 | `DELETE` | `/:type/config` | admin | Delete a workflow configuration (cascade) |
 | `GET` | `/:type/input-lookups` | RBAC | Resolve the config's pinned knowledge lookups (invoke predicate) |
 | `POST` | `/:type/invoke` | RBAC | Invoke a workflow (requires `invocable: true`) |
-| `GET` | `/:workflowId/status` | any | Workflow status |
-| `GET` | `/:workflowId/result` | any | Get workflow result (200 if complete, 202 if running) |
-| `POST` | `/:workflowId/terminate` | any | Terminate a running workflow |
-| `GET` | `/:workflowId/export` | any | Raw state export (convenience alias) |
+| `GET` | `/:workflowId/status` | builder | Workflow status |
+| `GET` | `/:workflowId/result` | builder or run owner | Get workflow result (200 if complete, 202 if running) |
+| `POST` | `/:workflowId/terminate` | builder | Terminate a running workflow |
+| `GET` | `/:workflowId/export` | builder | Raw state export (convenience alias) |
 
 ### `/api/workflow-states`
 
 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
-| `GET` | `/:workflowId` | any | Raw state export with facet filtering |
-| `GET` | `/:workflowId/execution` | any | Structured execution history |
-| `GET` | `/:workflowId/status` | any | Status semaphore |
-| `GET` | `/:workflowId/state` | any | Current workflow state snapshot |
+| `GET` | `/:workflowId` | builder | Raw state export with facet filtering |
+| `GET` | `/:workflowId/execution` | builder or run owner | Structured execution history |
+| `GET` | `/:workflowId/envelopes` | builder | Input and output envelopes |
+| `GET` | `/:workflowId/status` | builder | Status semaphore |
+| `GET` | `/:workflowId/state` | builder | Current workflow state snapshot |