Update API docs for 2.4 (#960)

- Update API specs for 2.4 (#960)
- Update API docs
- Regenerate Python docs

specs/README.md

@@ -28,8 +28,9 @@ specs/
 Location: `specs/api/openapi.yaml`
 
 The REST API specification documents:
-- **5 Global Services**: config, flow, librarian, knowledge, collection-management
-- **16 Flow-Hosted Services**: agent, RAG, embeddings, queries, loading, tools
+- **Global Services**: IAM (user management, authentication)
+- **5 Workspace-Scoped Services**: config, flow, librarian, knowledge, collection-management
+- **16 Flow-Scoped Services**: agent, RAG, embeddings, queries, loading, tools
 - **Import/Export**: Bulk data operations
 - **Metrics**: Prometheus monitoring
 

specs/api/README.md

@@ -2,6 +2,55 @@
 
 This directory contains the modular OpenAPI 3.1 specification for the TrustGraph REST API Gateway.
 
+## Authentication
+
+Clients authenticate by passing an opaque bearer token in the
+`Authorization` header.  The gateway resolves the token to an
+authenticated identity and an associated workspace.  Tokens are
+obtained via the IAM service (e.g. `tg-login` or `tg-create-api-key`).
+
+## Service Tiers
+
+API services are organized into three tiers based on their scoping:
+
+### Global services
+
+These services are not scoped to a workspace.  They manage
+system-wide resources.
+
+- **IAM** — user management, authentication, API key lifecycle
+
+### Workspace-scoped services
+
+These services operate within the workspace associated with the
+authenticated token.  The workspace is resolved by the gateway from
+the bearer token — it is not passed as an explicit parameter.
+
+- **Config** — configuration management (prompts, token costs, etc.)
+- **Librarian** — document library management
+- **Knowledge** — knowledge graph core management
+- **Collection Management** — collection metadata
+- **Flow** — flow lifecycle and blueprint management
+
+### Flow-scoped services
+
+These services require a `flow` parameter identifying the processing
+flow to use, in addition to the workspace context from the token.
+
+- **Agent** — agentic AI interactions
+- **Document RAG** — retrieval-augmented generation over documents
+- **Graph RAG** — retrieval-augmented generation over knowledge graphs
+- **Text Completion** — LLM text completion
+- **Prompt** — prompt template expansion
+- **Embeddings** — vector embedding generation
+- **SPARQL Query** — SPARQL queries against the knowledge graph
+- **Graph Embeddings** — knowledge graph embedding queries
+- **Document Embeddings** — document embedding queries
+- **Structured Query** — structured data queries
+- **Row Embeddings** — structured data embedding queries
+- **Rows Query** — row-level data queries
+- **Triples Query** — knowledge graph triple queries
+
 ## Structure
 
 ```

specs/api/components/schemas/collection/CollectionRequest.yaml

@@ -14,7 +14,7 @@ properties:
       - delete-collection
     description: |
       Collection operation:
-      - `list-collections`: List collections in workspace
+      - `list-collections`: List collections in the current workspace (resolved from token)
       - `update-collection`: Create or update collection metadata
       - `delete-collection`: Delete collection
   collection:

specs/api/components/schemas/knowledge/KnowledgeRequest.yaml

@@ -18,7 +18,7 @@ properties:
       - unload-kg-core
     description: |
       Knowledge core operation:
-      - `list-kg-cores`: List knowledge cores in workspace
+      - `list-kg-cores`: List knowledge cores in the current workspace (resolved from token)
       - `get-kg-core`: Get knowledge core by ID
       - `put-kg-core`: Store triples and/or embeddings
       - `delete-kg-core`: Delete knowledge core by ID

specs/api/openapi.yaml

@@ -2,21 +2,44 @@ openapi: 3.1.0
 
 info:
   title: TrustGraph API Gateway
-  version: "2.2"
+  version: "2.4"
   description: |
     REST API for TrustGraph - an AI-powered knowledge graph and RAG system.
 
     ## Overview
 
     The API provides access to:
-    - **Global Services**: Configuration, flow management, knowledge storage, library management
-    - **Flow-Hosted Services**: AI services like RAG, text completion, embeddings (require running flow)
+    - **Global Services**: IAM (user management, authentication)
+    - **Workspace-Scoped Services**: Configuration, flow management, knowledge storage, library management
+    - **Flow-Scoped Services**: AI services like RAG, text completion, embeddings (require running flow)
     - **Import/Export**: Bulk data operations for triples, embeddings, entity contexts
     - **WebSocket**: Multiplexed interface for all services
 
-    ## Service Types
+    ## Authentication
+
+    Clients authenticate by passing an opaque bearer token in the
+    `Authorization` header.  The token is obtained via the IAM service
+    (e.g. `tg-login` or `tg-create-api-key`).
+
+    ```
+    Authorization: Bearer <token>
+    ```
+
+    The gateway resolves the token to an authenticated identity and an
+    associated workspace.  The token is an opaque string — clients must
+    not make assumptions about its internal structure.
+
+    ## Service Tiers
 
     ### Global Services
+    System-wide services with no workspace scoping:
+    - `iam` - User management, authentication, API key lifecycle
+
+    ### Workspace-Scoped Services
+    Operate within the workspace associated with the authenticated
+    token.  The workspace is resolved by the gateway — it is not
+    passed as an explicit parameter.
+
     Fixed endpoints accessible via `/api/v1/{kind}`:
     - `config` - Configuration management
     - `flow` - Flow lifecycle and blueprints
@@ -24,24 +47,17 @@ info:
     - `knowledge` - Knowledge graph core management
     - `collection-management` - Collection metadata
 
-    ### Flow-Hosted Services
-    Require running flow instance, accessed via `/api/v1/flow/{flow}/service/{kind}`:
+    ### Flow-Scoped Services
+    Require a `flow` parameter identifying the processing flow to use.
+    Workspace context comes from the authenticated token.
+
+    Accessed via `/api/v1/flow/{flow}/service/{kind}`:
     - AI services: agent, text-completion, prompt, RAG (document/graph)
     - Embeddings: embeddings, graph-embeddings, document-embeddings
     - Query: triples, rows, nlp-query, structured-query, sparql-query, row-embeddings
     - Data loading: text-load, document-load
     - Utilities: mcp-tool, structured-diag
 
-    ## Authentication
-
-    Bearer token authentication when `GATEWAY_SECRET` environment variable is set.
-    Include token in Authorization header:
-    ```
-    Authorization: Bearer <token>
-    ```
-
-    If `GATEWAY_SECRET` is not set, API runs without authentication (development mode).
-
     ## Field Naming
 
     All JSON fields use **kebab-case**: `flow-id`, `blueprint-name`, `doc-limit`, etc.
@@ -74,17 +90,17 @@ security:
 
 tags:
   - name: Config
-    description: Configuration management (global service)
+    description: Configuration management (workspace-scoped)
   - name: Flow
-    description: Flow lifecycle and blueprint management (global service)
+    description: Flow lifecycle and blueprint management (workspace-scoped)
   - name: Librarian
-    description: Document library management (global service)
+    description: Document library management (workspace-scoped)
   - name: Knowledge
-    description: Knowledge graph core management (global service)
+    description: Knowledge graph core management (workspace-scoped)
   - name: Collection
-    description: Collection metadata management (global service)
+    description: Collection metadata management (workspace-scoped)
   - name: Flow Services
-    description: Services hosted within flow instances
+    description: AI and query services hosted within flow instances (flow-scoped)
   - name: Import/Export
     description: Bulk data import and export
   - name: WebSocket

specs/api/paths/collection-management.yaml

@@ -1,10 +1,13 @@
 post:
   tags:
     - Collection
-  summary: Collection metadata management
+  summary: Collection metadata management (workspace-scoped)
   description: |
     Manage collection metadata for organizing documents and knowledge.
 
+    This is a **workspace-scoped** service. All operations apply to the
+    workspace associated with the authenticated bearer token.
+
     ## Collections
 
     Collections are organizational units for grouping:

specs/api/paths/config.yaml

@@ -1,9 +1,13 @@
 post:
   tags:
     - Config
-  summary: Configuration service
+  summary: Configuration service (workspace-scoped)
   description: |
-    Manage TrustGraph configuration including flows, prompts, token costs, parameter types, and more.
+    Manage TrustGraph configuration including flows, prompts, token costs,
+    parameter types, and more.
+
+    This is a **workspace-scoped** service. All operations apply to the
+    workspace associated with the authenticated bearer token.
 
     ## Operations
 

specs/api/paths/flow.yaml

@@ -1,10 +1,13 @@
 post:
   tags:
     - Flow
-  summary: Flow lifecycle and blueprint management
+  summary: Flow lifecycle and blueprint management (workspace-scoped)
   description: |
     Manage flow instances and blueprints.
 
+    This is a **workspace-scoped** service. All operations apply to the
+    workspace associated with the authenticated bearer token.
+
     ## Important Distinction
 
     The **flow service** manages *running flow instances*.

specs/api/paths/flow/agent.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     AI agent that can understand questions, reason about them, and take actions.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Agent Overview
 
     The agent service provides a conversational AI that:

specs/api/paths/flow/document-embeddings.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query document embeddings to find similar text chunks by vector similarity.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Document Embeddings Query Overview
 
     Find document chunks semantically similar to a query vector:

specs/api/paths/flow/document-load.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Load binary documents (PDF, Word, etc.) into processing pipeline.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Document Load Overview
 
     Fire-and-forget binary document loading:

specs/api/paths/flow/document-rag.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Retrieval-Augmented Generation over document embeddings.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Document RAG Overview
 
     Document RAG combines:

specs/api/paths/flow/embeddings.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Convert text to embedding vectors for semantic similarity search.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Embeddings Overview
 
     Embeddings transform text into dense vector representations that:

specs/api/paths/flow/graph-embeddings.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query graph embeddings to find similar entities by vector similarity.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Graph Embeddings Query Overview
 
     Find entities semantically similar to a query vector:

specs/api/paths/flow/graph-rag.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Retrieval-Augmented Generation over knowledge graph.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Graph RAG Overview
 
     Graph RAG combines:

specs/api/paths/flow/mcp-tool.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Execute MCP (Model Context Protocol) tools for agent capabilities.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## MCP Tool Overview
 
     MCP tools provide agent capabilities through standardized protocol:

specs/api/paths/flow/nlp-query.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Convert natural language questions to structured GraphQL queries.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## NLP Query Overview
 
     Transforms user questions into executable GraphQL:

specs/api/paths/flow/prompt.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Execute stored prompt templates with variable substitution.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Prompt Service Overview
 
     The prompt service enables:

specs/api/paths/flow/row-embeddings.yaml

@@ -4,6 +4,11 @@ post:
   summary: Row Embeddings Query - semantic search on structured data
   description: |
     Query row embeddings to find similar rows by vector similarity on indexed fields.
+
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     Enables fuzzy/semantic matching on structured data.
 
     ## Row Embeddings Query Overview

specs/api/paths/flow/rows.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query structured data using GraphQL for row-oriented data access.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Rows Query Overview
 
     GraphQL interface to structured data:

specs/api/paths/flow/sparql-query.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Execute a SPARQL 1.1 query against the knowledge graph.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Supported Query Types
 
     - **SELECT**: Returns variable bindings as a table of results

specs/api/paths/flow/structured-diag.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Analyze and understand structured data (CSV, JSON, XML).
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Structured Diag Overview
 
     Helps process unknown structured data:

specs/api/paths/flow/structured-query.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Ask natural language questions and get results directly.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Structured Query Overview
 
     Combines two operations in one call:

specs/api/paths/flow/text-completion.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Direct text completion using LLM without retrieval augmentation.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Text Completion Overview
 
     Pure LLM generation for:

specs/api/paths/flow/text-load.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Load text documents into processing pipeline for indexing and embedding.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Text Load Overview
 
     Fire-and-forget document loading:

specs/api/paths/flow/triples.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query knowledge graph using subject-predicate-object patterns.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Triples Query Overview
 
     Query RDF triples with flexible pattern matching:

specs/api/paths/knowledge.yaml

@@ -1,9 +1,13 @@
 post:
   tags:
     - Knowledge
-  summary: Knowledge graph core management
+  summary: Knowledge graph core management (workspace-scoped)
   description: |
-    Manage knowledge graph cores - persistent storage of triples and embeddings.
+    Manage knowledge graph cores - persistent storage of triples and
+    embeddings.
+
+    This is a **workspace-scoped** service. All operations apply to the
+    workspace associated with the authenticated bearer token.
 
     ## Knowledge Cores
 

specs/api/paths/librarian.yaml

@@ -1,9 +1,13 @@
 post:
   tags:
     - Librarian
-  summary: Document library management
+  summary: Document library management (workspace-scoped)
   description: |
-    Manage document library: add, remove, list documents, and control processing.
+    Manage document library: add, remove, list documents, and control
+    processing.
+
+    This is a **workspace-scoped** service. All operations apply to the
+    workspace associated with the authenticated bearer token.
 
     ## Document Library
 

specs/api/paths/websocket.yaml

@@ -26,7 +26,7 @@ get:
 
     ### Request Message Format
 
-    **Global Service Request** (no flow parameter):
+    **Workspace-Scoped Service Request** (no flow parameter):
     ```json
     {
       "id": "req-123",
@@ -38,7 +38,7 @@ get:
     }
     ```
 
-    **Flow-Hosted Service Request** (with flow parameter):
+    **Flow-Scoped Service Request** (with flow parameter):
     ```json
     {
       "id": "req-456",
@@ -54,7 +54,7 @@ get:
     **Request Fields**:
     - `id` (string, required): Client-generated unique identifier for this request within the session. Used to match responses to requests.
     - `service` (string, required): Service identifier (e.g., "config", "agent", "document-rag"). Same as `{kind}` in REST URLs.
-    - `flow` (string, optional): Flow ID for flow-hosted services. Omit for global services.
+    - `flow` (string, optional): Flow ID for flow-scoped services. Omit for workspace-scoped and global services.
     - `request` (object, required): Service-specific request payload. Same structure as REST API request body.
 
     ### Response Message Format
@@ -96,14 +96,14 @@ get:
     | `POST /api/v1/config` | `{"service": "config"}` |
     | `POST /api/v1/flow/{flow}/service/agent` | `{"service": "agent", "flow": "my-flow"}` |
 
-    **Global Services** (no `flow` parameter):
+    **Workspace-Scoped Services** (no `flow` parameter, workspace from token):
     - `config` - Configuration management
     - `flow` - Flow lifecycle and blueprints
     - `librarian` - Document library management
     - `knowledge` - Knowledge graph core management
     - `collection-management` - Collection metadata
 
-    **Flow-Hosted Services** (require `flow` parameter):
+    **Flow-Scoped Services** (require `flow` parameter, workspace from token):
     - AI services: `agent`, `text-completion`, `prompt`, `document-rag`, `graph-rag`
     - Embeddings: `embeddings`, `graph-embeddings`, `document-embeddings`
     - Query: `triples`, `objects`, `nlp-query`, `structured-query`
@@ -146,9 +146,11 @@ get:
 
     ## Authentication
 
-    When `GATEWAY_SECRET` is set, include bearer token:
-    - As query parameter: `ws://localhost:8088/api/v1/socket?token=<token>`
-    - Or in WebSocket subprotocol header
+    The `/api/v1/socket` endpoint uses in-band authentication.
+    The WebSocket handshake is accepted unconditionally.  After
+    connecting, the client sends a bearer token as the first frame.
+    The gateway resolves the token to an identity and workspace.
+    All subsequent requests operate within that workspace context.
 
     ## Benefits Over REST
 

specs/api/security/bearerAuth.yaml

@@ -3,10 +3,19 @@ scheme: bearer
 description: |
   Bearer token authentication.
 
-  Set via `GATEWAY_SECRET` environment variable on the gateway.
-  If `GATEWAY_SECRET` is not set, authentication is disabled (development mode).
+  Clients authenticate by passing an opaque token in the
+  `Authorization` header. The token is treated as an opaque string by
+  clients — its internal structure is a gateway implementation detail
+  and must not be relied upon.
+
+  The gateway resolves the token to an authenticated identity and an
+  associated workspace. All workspace-scoped and flow-scoped operations
+  then execute within that workspace context.
+
+  Tokens are obtained via the IAM service (e.g. `tg-login` or
+  `tg-create-api-key`).
 
   Example:
   ```
-  Authorization: Bearer your-secret-token
+  Authorization: Bearer <token>
   ```

specs/build-docs.sh

@@ -24,7 +24,7 @@ echo
 # Build WebSocket API documentation
 echo "Building WebSocket API documentation (AsyncAPI)..."
 cd ../websocket
-npx --yes -p @asyncapi/cli asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o /tmp/asyncapi-build -p singleFile=true --force-write
+npx --yes @asyncapi/cli generate fromTemplate asyncapi.yaml @asyncapi/html-template -o /tmp/asyncapi-build -p singleFile=true --force-write --use-new-generator
 mv /tmp/asyncapi-build/index.html ../../docs/websocket.html
 rm -rf /tmp/asyncapi-build
 echo "✓ WebSocket API docs generated: docs/websocket.html"

specs/websocket/asyncapi.yaml

@@ -2,7 +2,7 @@ asyncapi: 3.0.0
 
 info:
   title: TrustGraph WebSocket API
-  version: "2.2"
+  version: "2.4"
   description: |
     WebSocket API for TrustGraph - providing multiplexed, asynchronous access to all services.
 
@@ -14,21 +14,35 @@ info:
     - **Efficient**: Lower overhead than HTTP REST
     - **Streaming**: Real-time progressive responses
 
+    ## Authentication
+
+    The `/api/v1/socket` endpoint uses **in-band authentication**.
+    The WebSocket handshake is accepted unconditionally. The client
+    must authenticate by sending a bearer token as the first message
+    after connecting.  The gateway resolves the token to an
+    authenticated identity and workspace.
+
+    All subsequent requests execute within the workspace context
+    established by the authentication frame.
+
     ## Protocol Summary
 
     All messages are JSON with:
     - `id`: Client-generated unique identifier for request/response correlation
     - `service`: Service identifier (e.g., "config", "agent", "document-rag")
-    - `flow`: Optional flow ID for flow-hosted services
+    - `flow`: Optional flow ID for flow-scoped services
     - `request`/`response`: Service-specific payload (identical to REST API schemas)
     - `error`: Error information on failure
 
-    ## Service Types
+    ## Service Tiers
 
-    **Global Services** (no `flow` parameter):
+    **Global Services** (no workspace scoping):
+    - iam
+
+    **Workspace-Scoped Services** (workspace resolved from token):
     - config, flow, librarian, knowledge, collection-management
 
-    **Flow-Hosted Services** (require `flow` parameter):
+    **Flow-Scoped Services** (require `flow` parameter, workspace from token):
     - agent, text-completion, prompt, document-rag, graph-rag
     - embeddings, graph-embeddings, document-embeddings
     - triples, rows, nlp-query, structured-query, sparql-query, structured-diag, row-embeddings
@@ -64,11 +78,14 @@ components:
   securitySchemes:
     bearerAuth:
       type: httpApiKey
-      name: token
-      in: query
+      name: Authorization
+      in: header
       description: |
-        Bearer token authentication when GATEWAY_SECRET is configured.
-        Include as query parameter: ws://localhost:8088/api/v1/socket?token=<token>
+        Bearer token authentication.  The `/api/v1/socket` endpoint
+        uses in-band authentication: the WebSocket handshake is
+        accepted unconditionally and the client sends a bearer token
+        as the first frame after connecting.  The token is an opaque
+        string obtained via the IAM service.
 
   messages:
     ServiceRequest:

specs/websocket/channels/socket.yaml

@@ -3,8 +3,16 @@ description: |
   Primary WebSocket channel for all TrustGraph services.
 
   This single channel provides multiplexed access to:
-  - All global services (config, flow, librarian, knowledge, collection-management)
-  - All flow-hosted services (agent, RAG, embeddings, queries, loading, etc.)
+  - Global services (IAM)
+  - Workspace-scoped services (config, flow, librarian, knowledge, collection-management)
+  - Flow-scoped services (agent, RAG, embeddings, queries, loading, etc.)
+
+  ## Authentication
+
+  The handshake is accepted unconditionally.  The client must send a
+  bearer token as the first frame after connecting (in-band auth).
+  The gateway resolves the token to an identity and workspace.  All
+  subsequent requests execute within that workspace context.
 
   ## Multiplexing
 
@@ -13,16 +21,17 @@ description: |
 
   ## Message Flow
 
-  1. Client sends request with unique `id`, `service`, optional `flow`, and `request` payload
-  2. Server processes request asynchronously
-  3. Server sends response(s) with matching `id` and either `response` or `error`
-  4. For streaming services, multiple responses may be sent with the same `id`
+  1. Client connects and sends bearer token as first frame (authentication)
+  2. Client sends requests with unique `id`, `service`, optional `flow`, and `request` payload
+  3. Server processes request asynchronously
+  4. Server sends response(s) with matching `id` and either `response` or `error`
+  5. For streaming services, multiple responses may be sent with the same `id`
 
   ## Service Routing
 
   Messages are routed to services based on:
   - `service`: Service identifier (required)
-  - `flow`: Flow ID (required for flow-hosted services, omitted for global services)
+  - `flow`: Flow ID (required for flow-scoped services, omitted for workspace-scoped and global services)
 
 messages:
   request:

specs/websocket/components/messages/ServiceRequest.yaml

@@ -9,14 +9,14 @@ description: |
 payload:
   description: Service request envelope with id, service, optional flow, and service-specific request payload
   oneOf:
-    # Global services (no flow parameter)
+    # Workspace-scoped services (no flow parameter)
     - $ref: './requests/ConfigRequest.yaml'
     - $ref: './requests/FlowRequest.yaml'
     - $ref: './requests/LibrarianRequest.yaml'
     - $ref: './requests/KnowledgeRequest.yaml'
     - $ref: './requests/CollectionManagementRequest.yaml'
 
-    # Flow-hosted services (require flow parameter)
+    # Flow-scoped services (require flow parameter)
     - $ref: './requests/AgentRequest.yaml'
     - $ref: './requests/DocumentRagRequest.yaml'
     - $ref: './requests/GraphRagRequest.yaml'

specs/websocket/components/messages/requests/AgentRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for agent service (flow-hosted service)
+description: WebSocket request for agent service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/CollectionManagementRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for collection-management service (global service)
+description: WebSocket request for collection-management service (workspace-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/ConfigRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for config service (global service)
+description: WebSocket request for config service (workspace-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/DocumentEmbeddingsRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for document-embeddings service (flow-hosted service)
+description: WebSocket request for document-embeddings service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/DocumentLoadRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for document-load service (flow-hosted service)
+description: WebSocket request for document-load service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/DocumentRagRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for document-rag service (flow-hosted service)
+description: WebSocket request for document-rag service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/EmbeddingsRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for embeddings service (flow-hosted service)
+description: WebSocket request for embeddings service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/FlowRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for flow service (global service)
+description: WebSocket request for flow service (workspace-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/GraphEmbeddingsRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for graph-embeddings service (flow-hosted service)
+description: WebSocket request for graph-embeddings service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/GraphRagRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for graph-rag service (flow-hosted service)
+description: WebSocket request for graph-rag service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/KnowledgeRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for knowledge service (global service)
+description: WebSocket request for knowledge service (workspace-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/LibrarianRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for librarian service (global service)
+description: WebSocket request for librarian service (workspace-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/McpToolRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for mcp-tool service (flow-hosted service)
+description: WebSocket request for mcp-tool service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/NlpQueryRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for nlp-query service (flow-hosted service)
+description: WebSocket request for nlp-query service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/PromptRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for prompt service (flow-hosted service)
+description: WebSocket request for prompt service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/RowEmbeddingsRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for row-embeddings service (flow-hosted service)
+description: WebSocket request for row-embeddings service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/RowsRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for rows service (flow-hosted service)
+description: WebSocket request for rows service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/SparqlQueryRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for sparql-query service (flow-hosted service)
+description: WebSocket request for sparql-query service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/StructuredDiagRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for structured-diag service (flow-hosted service)
+description: WebSocket request for structured-diag service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/StructuredQueryRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for structured-query service (flow-hosted service)
+description: WebSocket request for structured-query service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/TextCompletionRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for text-completion service (flow-hosted service)
+description: WebSocket request for text-completion service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/TextLoadRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for text-load service (flow-hosted service)
+description: WebSocket request for text-load service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/messages/requests/TriplesRequest.yaml

@@ -1,5 +1,5 @@
 type: object
-description: WebSocket request for triples service (flow-hosted service)
+description: WebSocket request for triples service (flow-scoped service)
 required:
   - id
   - service

specs/websocket/components/schemas/RequestEnvelope.yaml

@@ -23,8 +23,9 @@ properties:
     description: |
       Service identifier. Same as {kind} in REST API URLs.
 
-      Global services: config, flow, librarian, knowledge, collection-management
-      Flow-hosted services: agent, text-completion, prompt, document-rag, graph-rag,
+      Global services: iam
+      Workspace-scoped services: config, flow, librarian, knowledge, collection-management
+      Flow-scoped services: agent, text-completion, prompt, document-rag, graph-rag,
       embeddings, graph-embeddings, document-embeddings, triples, objects,
       nlp-query, structured-query, structured-diag, text-load, document-load, mcp-tool
     examples:
@@ -34,10 +35,12 @@ properties:
   flow:
     type: string
     description: |
-      Flow ID for flow-hosted services. Required for services accessed via
+      Flow ID for flow-scoped services. Required for services accessed via
       /api/v1/flow/{flow}/service/{kind} in REST API.
 
-      Omit this field for global services (config, flow, librarian, knowledge, collection-management).
+      Omit for global services (iam) and workspace-scoped services
+      (config, flow, librarian, knowledge, collection-management).
+      Workspace context is resolved from the authenticated token.
     examples:
       - my-flow
       - production-flow

trustgraph-mcp/trustgraph/mcp_server/tg_socket.py

@@ -15,6 +15,11 @@ class WebSocketManager:
         self.token = token
         self.socket = None
 
+    # FIXME: authentication is broken. The /api/v1/socket endpoint uses
+    # in-band auth (first-frame protocol via the Mux dispatcher), not
+    # query-parameter tokens. This query-string token is silently ignored.
+    # Fix: after connect(), send an auth frame with the bearer token as
+    # the first message, matching the gateway's in-band auth protocol.
     def _build_url(self):
         if not self.token:
             return self.url