API reference

Operator - Members

One tag: method, path, summary, auth, and scopes. Request and response fields ship in this page — expand a row to read the contract.

Browse docs

Endpoints

GET

/api/v1/operator/workspaces/:workspace_id/members Web Session

List workspace members

Description

Returns every membership row for the session's current workspace, including the owner. The envelope is `memberships` (not `members`). Each item is `role`, `status`, `last_seen_at`, `user{id,email}`, and `workspace{id,name}` — not a flat `user_id` / `workspace_id` / `user.name` shape. `:workspace_id` must equal the session workspace; any other UUID is 404. Browser session + CSRF only; machine Bearer tokens are 401.

Auth

Web Session

Parameters

Name	In	Type	Required	Description
workspace_id	path	string	Yes	Must be the session's current workspace UUID

Responses

200

Membership rows for the current workspace

Returns: MembershipList

Response Body

Field	Type	Required	Description
memberships	array<object>	Yes	Membership records
memberships[].id	string	Yes	Membership UUID
memberships[].status	string (active, invited, disabled)	Yes	Membership status
memberships[].user	object	Yes	Member user (id and email only; name is not rendered)
memberships[].user.id	string	Yes	User UUID
memberships[].user.email	string	Yes	User email
memberships[].role	string (owner, admin, member, auditor)	Yes	Workspace role
memberships[].inserted_at	datetime (ISO 8601)	Yes	Created at
memberships[].updated_at	datetime (ISO 8601)	Yes	Updated at
memberships[].workspace	object	Yes	Workspace summary
memberships[].workspace.id	string	Yes	Workspace UUID
memberships[].workspace.name	string	Yes	Workspace name
memberships[].last_seen_at	datetime (ISO 8601)	No	Last seen in the console

Example

{
  "memberships": [
    {
      "id": "c4d5e6f7-8901-4abc-def0-1234567890ab",
      "inserted_at": "2026-01-15T10:00:00Z",
      "last_seen_at": "2026-03-27T09:00:00Z",
      "role": "admin",
      "status": "active",
      "updated_at": "2026-03-27T09:00:00Z",
      "user": {
        "email": "[email protected]",
        "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
      },
      "workspace": {
        "id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
        "name": "Acme Corp"
      }
    }
  ]
}

401

No operator browser session

404

workspace_id is not the session's current workspace

PATCH

/api/v1/operator/workspaces/:workspace_id/members/:id Web Session

Update member role or status

Description

Writes `membership.role` and/or `membership.status`. Neither field is required; an empty `membership` object is a successful no-op. Roles are `member`, `admin`, and `auditor` — the API never promotes anyone to `owner`. Statuses are `active`, `invited`, and `disabled`. Setting status to anything other than `active` revokes every browser session for that user. Owner rows cannot be mutated (`400` `cannot_change_owner`), including sending `"role": "owner"`. Owner/admin only (`403` `admin_required`). `:workspace_id` must be the session workspace (otherwise 404).

Auth

Web Session

Request Body

Field	Type	Required	Description
membership	object	Yes	Membership attributes to update. All fields optional.
membership.status	string (active, invited, disabled)	No	New membership status. Non-active values revoke the member's sessions.
membership.role	string (member, admin, auditor)	No	New role. owner is refused with 400 cannot_change_owner.

Parameters

Name	In	Type	Required	Description
workspace_id	path	string	Yes	Must be the session's current workspace UUID
id	path	string	Yes	Membership UUID

Responses

200

Updated membership

Returns: Membership

Response Body

Field	Type	Required	Description
id	string	Yes	Membership UUID
status	string (active, invited, disabled)	Yes	Membership status
user	object	Yes	Member user (id and email only; name is not rendered)
user.id	string	Yes	User UUID
user.email	string	Yes	User email
role	string (owner, admin, member, auditor)	Yes	Workspace role
inserted_at	datetime (ISO 8601)	Yes	Created at
updated_at	datetime (ISO 8601)	Yes	Updated at
workspace	object	Yes	Workspace summary
workspace.id	string	Yes	Workspace UUID
workspace.name	string	Yes	Workspace name
last_seen_at	datetime (ISO 8601)	No	Last seen in the console

Example

{
  "id": "c4d5e6f7-8901-4abc-def0-1234567890ab",
  "inserted_at": "2026-01-15T10:00:00Z",
  "last_seen_at": "2026-03-27T09:00:00Z",
  "role": "admin",
  "status": "active",
  "updated_at": "2026-03-27T09:00:00Z",
  "user": {
    "email": "[email protected]",
    "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
  },
  "workspace": {
    "id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
    "name": "Acme Corp"
  }
}

400

Owner protection (`cannot_change_owner`) or other atom error as Problem JSON detail

401

No operator browser session

403

Owner or admin membership required

404

Membership not found, or workspace_id is not the current workspace

422

Invalid role or status

DELETE

/api/v1/operator/workspaces/:workspace_id/members/:id Web Session

Remove member

Description

Deletes a non-owner membership and revokes that user's browser sessions. Removing the owner is refused (`400` `cannot_remove_owner`). Owner/admin only. `:workspace_id` must be the session workspace.

Auth

Web Session

Parameters

Name	In	Type	Required	Description
workspace_id	path	string	Yes	Must be the session's current workspace UUID
id	path	string	Yes	Membership UUID

Responses

204

Member removed

400

Cannot remove the workspace owner (`cannot_remove_owner`)

401

No operator browser session

403

Owner or admin membership required

404

Membership not found, or workspace_id is not the current workspace