Operator - Members

Overview

Memberships join a user to a workspace with a role and lifecycle status. The operator API lists people in the current workspace and lets administrators change role or status, or remove a non-owner membership.

Role and status are authority

Roles are owner, admin, member, and auditor; status determines whether the membership is active. Changing either refreshes that user's connected authority so an open LiveView or socket cannot retain stale permissions.

The owner is protected

This API rejects promotion to owner, changing the existing owner's role, and removing the owner. Use an explicit ownership-transfer workflow rather than trying to bypass these invariants.

How it works

1. Identify the membership row

   List the selected workspace's memberships and use the membership id—not the user id—for update or delete. Confirm the nested user email and current role before changing authority.

2. Apply and verify

   Change only role or status, then re-read the list. Removed or deactivated users may have their connected sessions refreshed or revoked, so coordinate changes that affect on-call operators.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

const workspaceId = window.prompt("Current workspace UUID");
if (!workspaceId) throw new Error("A workspace UUID is required");
const response = await fetch(`/api/v1/operator/workspaces/${encodeURIComponent(workspaceId)}/members`, {
  credentials: "same-origin",
  headers: {"Accept": "application/json"}
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${body.detail}`);
console.log(body);

Troubleshooting

A known workspace returns 404

Membership routes accept only the session's current workspace UUID. Select that workspace in the application before using its path.

An owner change is rejected

That protection is intentional. The membership update accepts role and status for non-owner rows but cannot create, modify, or remove workspace ownership.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.

{
  "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": "admin@acme.com",
        "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
      },
      "workspace": {
        "id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
        "name": "Acme Corp"
      }
    }
  ]
}

{
  "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": "admin@acme.com",
    "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
  },
  "workspace": {
    "id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
    "name": "Acme Corp"
  }
}