Workspace Members

Manage members within a workspace, including role assignment, invitations, and member search.

Base Path: /api/v1/workspaces/{workspaceId}/members Authentication: Required (Bearer Token) Tag: Workspace Members

---

List Members

Retrieve all members of a workspace.

GET /workspaces/{workspaceId}/members

Path Parameters

Parameter	Type	Description
workspaceId	UUID	Workspace ID

Response

{
  "success": true,
  "data": [
    {
      "id": "aae8400-e29b-41d4-a716-446655440000",
      "userId": "880e8400-e29b-41d4-a716-446655440000",
      "userName": "John Doe",
      "userEmail": "[email protected]",
      "userAvatar": "https://...",
      "role": "OWNER",
      "status": "ACTIVE",
      "invitedBy": {
        "id": "880e8400-e29b-41d4-a716-446655440000",
        "name": "John Doe",
        "avatar": "https://..."
      },
      "invitedAt": "2025-01-01T00:00:00Z",
      "acceptedAt": "2025-01-01T00:00:00Z",
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}

Response Type: ApiResponse<List<WorkspaceMemberResponse>>

---

Invite Member

Invite a user to the workspace by email. Creates a pending invitation with a unique token.

POST /workspaces/{workspaceId}/members/invite

Request Body

{
  "email": "[email protected]",
  "role": "EDITOR",
  "message": "Welcome to our team!"
}

Field	Type	Required	Validation	Description
email	String	Yes	Valid email, max 255 chars	Invitee's email
role	WorkspaceRole	Yes	Not null	Assigned role
message	String	No	Max 500 chars	Custom invitation message

Response

Status: 201 Created

{
  "success": true,
  "data": {
    "invitationId": "...",
    "email": "[email protected]",
    "role": "EDITOR",
    "expiresAt": "2025-02-15T00:00:00Z",
    "inviteLink": "https://app.util4dev.com/invite/TOKEN"
  }
}

Response Type: ApiResponse<InvitationResultResponse>

:::info Required Role ADMIN or OWNER role required to invite members. :::

---

Update Member Role

Change a member's role within the workspace.

PUT /workspaces/{workspaceId}/members/{memberId}/role

Path Parameters

Parameter	Type	Description
workspaceId	UUID	Workspace ID
memberId	UUID	Member ID

Request Body

{
  "role": "ADMIN"
}

Field	Type	Required	Description
role	WorkspaceRole	Yes	New role (OWNER, ADMIN, EDITOR, COMMENTER, VIEWER)

Response Type: ApiResponse<WorkspaceMemberResponse>

:::info Required Role ADMIN or OWNER role required. Cannot change the role of someone with a higher role level. :::

---

Remove Member

Remove a member from the workspace.

DELETE /workspaces/{workspaceId}/members/{memberId}

Path Parameters

Parameter	Type	Description
workspaceId	UUID	Workspace ID
memberId	UUID	Member ID to remove

Status: 204 No Content

:::info Required Role ADMIN or OWNER role required. Cannot remove a member with a higher role level. :::

---

Search Members

Search workspace members by name or email (useful for @mention autocomplete).

GET /workspaces/{workspaceId}/members/search?q={query}

Query Parameters

Parameter	Type	Required	Default	Description
q	String	No	""	Search query (name or email)

Response

{
  "success": true,
  "data": [
    {
      "userId": "880e8400-e29b-41d4-a716-446655440000",
      "name": "John Doe",
      "email": "[email protected]",
      "avatar": "https://...",
      "role": "EDITOR"
    }
  ]
}

Response Type: ApiResponse<List<MemberSearchResponse>>

---

Leave Workspace

The authenticated user leaves the workspace voluntarily.

POST /workspaces/{workspaceId}/members/leave

Path Parameters

Parameter	Type	Description
workspaceId	UUID	Workspace ID

Status: 204 No Content

warning

Workspace owners cannot leave their own workspace. Transfer ownership first using the Transfer Ownership endpoint.