Workspace members
List and manage explicit workspace assignments with a workspace Admin or Owner key.
Members under /api/v1/workspace-members. Workspace-scoped API key with Admin or Owner authority is required. Missing/invalid tokens return 401; valid tokens without current admin authority return 403.
This API assigns existing organization members to a workspace. It does not send external invitations. Invite a person to the organization first through /api/organization-members, then assign that member here.
Endpoints
| Method | Path | Auth | Envelope |
|---|---|---|---|
| GET | /api/v1/workspace-members | Admin/Owner workspace key | { members[] } |
| POST | /api/v1/workspace-members | Admin/Owner workspace key | 201 { member } |
| PATCH | /api/v1/workspace-members | Admin/Owner workspace key | { member } |
| DELETE | /api/v1/workspace-members | Admin/Owner workspace key | { removed: true } |
Management without Admin/Owner returns 403.
Member object
id, workspaceId, name, email, role (Owner | Admin | Member | Viewer), status, presence, and lastActiveAt.
GET returns explicit workspace memberships. Organization invitations are listed separately by /api/organization-members.
Assign an organization member
POST JSON:
| Field | Notes |
|---|---|
email | Required. The email must already belong to a member of the workspace organization. |
role | Optional. Allowed: admin, member, viewer (lowercase). Default member. owner or other values → 400 { "error": "Member role must be admin, member, or viewer." } |
If the email is not an active organization member, the API returns 409 with organization_membership_required. It creates no workspace invitation or membership. You cannot assign Owner through POST.
Change a role or transfer ownership
PATCH JSON accepts id, role, and optional transferOwnership. Roles are owner, admin, member, or viewer. Promoting a new Owner requires transferOwnership: true; the acting Owner is demoted atomically. The API rejects any mutation that would leave the workspace without an Owner.
Remove an assignment
DELETE JSON accepts id, the workspace membership ID. Removal revokes explicit workspace access and dependent credentials atomically. It does not remove the person from the organization.
Known gaps
- Presence is not a live presence protocol.
- No
Idempotency-Key; assignment uses the existing organization user and workspace identity.