Skip to main content
Team members and role-based access control (RBAC) enables workspace collaboration with granular permission management.

​
Quick Start

1

Add a Member

# Add a member with basic member role
curl -X POST http://localhost:8000/api/v1/workspaces/{workspace_id}/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user-abc123","role":"member"}'
2

Update Member Role

# Promote member to admin
curl -X PATCH http://localhost:8000/api/v1/workspaces/{workspace_id}/members/{user_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role":"admin"}'
3

List All Members

# View all workspace members
curl http://localhost:8000/api/v1/workspaces/{workspace_id}/members \
  -H "Authorization: Bearer $TOKEN"

​
How It Works

RoleAdd MembersManage SettingsCreate IssuesRemove Members
Owner✅✅✅✅
Admin✅✅✅✅
Member❌❌✅❌

​
API Endpoints

​
Add Member

Add a new member to the workspace with a specific role. 
curl -X POST http://localhost:8000/api/v1/workspaces/{workspace_id}/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-abc123",
    "role": "member"
  }'

​
List Members

Retrieve all members in the workspace. 
curl http://localhost:8000/api/v1/workspaces/{workspace_id}/members \
  -H "Authorization: Bearer $TOKEN"

​
Update Member Role

Change a member’s role within the workspace. 
curl -X PATCH http://localhost:8000/api/v1/workspaces/{workspace_id}/members/{user_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

​
Remove Member

Remove a member from the workspace. 
curl -X DELETE http://localhost:8000/api/v1/workspaces/{workspace_id}/members/{user_id} \
  -H "Authorization: Bearer $TOKEN"

​
Role Hierarchy

​
Role Capabilities

CapabilityOwnerAdminMember
Member Management
Add members✅✅❌
Remove members✅✅❌
Update member roles✅✅❌
Workspace Settings
Modify workspace settings✅✅❌
Delete workspace✅❌❌
Content Management
Create issues/tasks✅✅✅
Edit own content✅✅✅
Edit others’ content✅✅❌

​
Schema Reference

​
Add Member Request

FieldTypeRequiredDescription
user_idstring✅Unique identifier for the user
rolestring✅Role to assign: owner, admin, or member
{
  "user_id": "user-abc123",
  "role": "member"
}

​
Update Role Request

FieldTypeRequiredDescription
rolestring✅New role: owner, admin, or member
{
  "role": "admin"
}

​
Member Response

FieldTypeDescription
idstringUnique member ID
workspace_idstringWorkspace identifier
user_idstringUser identifier
rolestringCurrent role
created_atstringISO 8601 timestamp
{
  "id": "mem-abc123",
  "workspace_id": "ws-abc123",
  "user_id": "user-abc123",
  "role": "admin",
  "created_at": "2025-01-01T00:00:00"
}

​
Best Practices

Always assign the minimum role required for a user’s responsibilities. Start with member role and promote only when necessary for their workspace functions.
Periodically review member roles and permissions. Remove inactive members and adjust roles based on changing responsibilities within the workspace.
Limit the number of owners in a workspace. Having too many owners can create security risks and confusion about who has ultimate responsibility.
Always use secure JWT tokens for API authentication. Store tokens securely and rotate them regularly to maintain workspace security.

​
Testing

Run the member management tests to verify functionality: 
pytest tests/test_services.py::TestMemberService -v
Expected test coverage includes:
  • Adding members with different roles
  • Role hierarchy validation
  • Permission enforcement
  • Member removal workflows

Workspace Management

Learn about workspace creation and management

Authentication

Understand JWT token authentication