feat: add list-my-workspaces operation and document IAM in API specs (#961)

Add a new `list-my-workspaces` operation so non-admin users can
discover which workspaces they have access to.  For OSS IAM, regular
users see their home workspace; admins see all workspaces.

Also add the full IAM service to both OpenAPI and AsyncAPI specs —
it was previously undocumented despite being a first-class service
on both HTTP and WebSocket interfaces.

specs/api/components/schemas/iam/ApiKeyInput.yaml

@@ -0,0 +1,21 @@
+type: object
+description: |
+  API key creation fields.  Used with `create-api-key`.
+properties:
+  user_id:
+    type: string
+    description: User to create the key for.
+    examples:
+      - usr_abc123
+  name:
+    type: string
+    description: Operator-facing label for the key (e.g. "laptop", "CI").
+    examples:
+      - laptop
+  expires:
+    type: string
+    description: |
+      Optional expiry timestamp in ISO-8601 UTC.  Empty string or
+      omitted means the key does not expire.
+    examples:
+      - "2027-01-01T00:00:00Z"

specs/api/components/schemas/iam/ApiKeyRecord.yaml

@@ -0,0 +1,38 @@
+type: object
+description: API key record returned by IAM operations.
+properties:
+  id:
+    type: string
+    description: Key identifier.
+    examples:
+      - key_xyz789
+  user_id:
+    type: string
+    description: Owning user identifier.
+    examples:
+      - usr_abc123
+  name:
+    type: string
+    description: Operator-facing label.
+    examples:
+      - laptop
+  prefix:
+    type: string
+    description: |
+      First 4 characters of the plaintext key, for identification
+      in listings.  Never enough to reconstruct the key.
+    examples:
+      - tg_a
+  expires:
+    type: string
+    description: Expiry timestamp (ISO-8601 UTC).  Empty if no expiry.
+    examples:
+      - "2027-01-01T00:00:00Z"
+  created:
+    type: string
+    description: Creation timestamp (ISO-8601 UTC).
+    examples:
+      - "2026-01-15T10:30:00Z"
+  last_used:
+    type: string
+    description: Last-used timestamp (ISO-8601 UTC).  Empty if never used.

specs/api/components/schemas/iam/IamRequest.yaml

@@ -0,0 +1,106 @@
+type: object
+description: |
+  IAM service request.
+
+  The IAM service is a **global service** — it operates at system level,
+  not scoped to a specific workspace.  All operations are dispatched via
+  the `operation` field.
+
+  Some operations require admin capabilities; others (like `whoami` and
+  `list-my-workspaces`) are available to any authenticated user.  See
+  the capability vocabulary for details.
+
+  The `actor` field is injected by the gateway and cannot be set by
+  the client.  It identifies the authenticated caller.
+required:
+  - operation
+properties:
+  operation:
+    type: string
+    enum:
+      - whoami
+      - list-my-workspaces
+      - create-user
+      - list-users
+      - get-user
+      - update-user
+      - disable-user
+      - enable-user
+      - delete-user
+      - create-workspace
+      - list-workspaces
+      - get-workspace
+      - update-workspace
+      - disable-workspace
+      - create-api-key
+      - list-api-keys
+      - revoke-api-key
+      - reset-password
+      - rotate-signing-key
+    description: |
+      Operation to perform.
+
+      **Any authenticated user:**
+      - `whoami`: Return the caller's own user record
+      - `list-my-workspaces`: List workspaces the caller has access to
+
+      **User management (requires `users:read`/`users:write`/`users:admin`):**
+      - `create-user`: Create a new user in a workspace
+      - `list-users`: List users (optionally filtered by workspace)
+      - `get-user`: Get a specific user record
+      - `update-user`: Update user fields (name, email, roles, enabled)
+      - `disable-user`: Soft-disable a user and revoke their API keys
+      - `enable-user`: Re-enable a previously disabled user
+      - `delete-user`: Hard-delete a user and their API keys
+
+      **Workspace management (requires `workspaces:admin`):**
+      - `create-workspace`: Create a new workspace
+      - `list-workspaces`: List all workspaces (admin view)
+      - `get-workspace`: Get a specific workspace record
+      - `update-workspace`: Update workspace name or enabled state
+      - `disable-workspace`: Disable workspace and all its users
+
+      **API key management (requires `keys:self` or `keys:admin`):**
+      - `create-api-key`: Create an API key for a user
+      - `list-api-keys`: List API keys for a user
+      - `revoke-api-key`: Revoke (delete) an API key
+
+      **Password management:**
+      - `reset-password`: Admin-initiated password reset (requires `users:admin`)
+
+      **System (requires `iam:admin`):**
+      - `rotate-signing-key`: Rotate the JWT signing key
+  workspace:
+    type: string
+    description: |
+      Workspace scope.  Required on workspace-scoped operations
+      (e.g. `create-user`).  Acts as an optional integrity check on
+      operations that target a user or key — when supplied, the target's
+      home workspace must match.
+
+      Omitted for system-level operations (`list-workspaces`,
+      `rotate-signing-key`) and for identity-resolution operations
+      (`whoami`, `list-my-workspaces`).
+    examples:
+      - default
+      - production
+  user_id:
+    type: string
+    description: |
+      Target user identifier.  Required for operations that act on a
+      specific user: `get-user`, `update-user`, `disable-user`,
+      `enable-user`, `delete-user`, `reset-password`, `list-api-keys`.
+    examples:
+      - usr_abc123
+  user:
+    $ref: './UserInput.yaml'
+  workspace_record:
+    $ref: './WorkspaceInput.yaml'
+  key:
+    $ref: './ApiKeyInput.yaml'
+  key_id:
+    type: string
+    description: |
+      API key identifier.  Required for `revoke-api-key`.
+    examples:
+      - key_xyz789

specs/api/components/schemas/iam/IamResponse.yaml

@@ -0,0 +1,51 @@
+type: object
+description: |
+  IAM service response.  Fields are populated depending on the
+  operation that was invoked.
+properties:
+  user:
+    $ref: './UserRecord.yaml'
+  users:
+    type: array
+    description: List of user records (populated by `list-users`).
+    items:
+      $ref: './UserRecord.yaml'
+  workspace:
+    $ref: './WorkspaceRecord.yaml'
+  workspaces:
+    type: array
+    description: |
+      List of workspace records (populated by `list-workspaces` and
+      `list-my-workspaces`).
+    items:
+      $ref: './WorkspaceRecord.yaml'
+  api_key_plaintext:
+    type: string
+    description: |
+      Plaintext API key.  Returned **once** by `create-api-key`.
+      Never populated on any other operation.  The caller must
+      capture this value — it cannot be retrieved again.
+  api_key:
+    $ref: './ApiKeyRecord.yaml'
+  api_keys:
+    type: array
+    description: List of API key records (populated by `list-api-keys`).
+    items:
+      $ref: './ApiKeyRecord.yaml'
+  temporary_password:
+    type: string
+    description: |
+      Temporary password returned once by `reset-password`.
+  error:
+    type: object
+    description: Error details (present on failure).
+    properties:
+      type:
+        type: string
+        description: |
+          Error type.  One of: `invalid-argument`, `not-found`,
+          `duplicate`, `auth-failed`, `weak-password`, `disabled`,
+          `operation-not-permitted`, `internal-error`.
+      message:
+        type: string
+        description: Human-readable error description (not surfaced to end users).

specs/api/components/schemas/iam/UserInput.yaml

@@ -0,0 +1,42 @@
+type: object
+description: |
+  User creation/update fields.  Used with `create-user` and `update-user`.
+  The `password` field is only accepted on `create-user`.
+properties:
+  username:
+    type: string
+    description: Login username.  Unique within a workspace.
+    examples:
+      - alice
+  name:
+    type: string
+    description: Display name.
+    examples:
+      - Alice Smith
+  email:
+    type: string
+    description: Email address.
+    examples:
+      - alice@example.com
+  password:
+    type: string
+    description: |
+      Initial password.  Only accepted on `create-user`; rejected on
+      `update-user`.  Use `reset-password` or `change-password` to
+      modify passwords.
+  roles:
+    type: array
+    items:
+      type: string
+    description: |
+      Roles to assign.  Open-source roles: `reader`, `writer`, `admin`.
+    examples:
+      - - reader
+  enabled:
+    type: boolean
+    description: Whether the user is enabled.
+    default: true
+  must_change_password:
+    type: boolean
+    description: Force password change on next login.
+    default: false

specs/api/components/schemas/iam/UserRecord.yaml

@@ -0,0 +1,46 @@
+type: object
+description: User record returned by IAM operations.
+properties:
+  id:
+    type: string
+    description: Unique user identifier.
+    examples:
+      - usr_abc123
+  workspace:
+    type: string
+    description: User's home workspace.
+    examples:
+      - default
+  username:
+    type: string
+    description: Login username (unique within workspace).
+    examples:
+      - alice
+  name:
+    type: string
+    description: Display name.
+    examples:
+      - Alice Smith
+  email:
+    type: string
+    description: Email address.
+    examples:
+      - alice@example.com
+  roles:
+    type: array
+    items:
+      type: string
+    description: Assigned roles.
+    examples:
+      - - reader
+  enabled:
+    type: boolean
+    description: Whether the user is enabled.
+  must_change_password:
+    type: boolean
+    description: Whether the user must change password on next login.
+  created:
+    type: string
+    description: Creation timestamp (ISO-8601 UTC).
+    examples:
+      - "2026-01-15T10:30:00Z"

specs/api/components/schemas/iam/WorkspaceInput.yaml

@@ -0,0 +1,23 @@
+type: object
+description: |
+  Workspace creation/update fields.  Used with `create-workspace` and
+  `update-workspace`.
+properties:
+  id:
+    type: string
+    description: |
+      Workspace identifier.  Required for all workspace operations.
+      Immutable after creation.
+    examples:
+      - default
+      - production
+  name:
+    type: string
+    description: Human-readable workspace name.
+    examples:
+      - Default Workspace
+      - Production
+  enabled:
+    type: boolean
+    description: Whether the workspace is enabled.
+    default: true

specs/api/components/schemas/iam/WorkspaceRecord.yaml

@@ -0,0 +1,21 @@
+type: object
+description: Workspace record returned by IAM operations.
+properties:
+  id:
+    type: string
+    description: Workspace identifier.
+    examples:
+      - default
+  name:
+    type: string
+    description: Human-readable workspace name.
+    examples:
+      - Default Workspace
+  enabled:
+    type: boolean
+    description: Whether the workspace is enabled.
+  created:
+    type: string
+    description: Creation timestamp (ISO-8601 UTC).
+    examples:
+      - "2026-01-01T00:00:00Z"