Skip to content

Team Members Management - Implementation Guide

🎯 Overview

Complete implementation for listing, viewing, and removing team members with role assignment capabilities.

✅ What's Been Implemented

Backend

New Endpoints

  1. GET /api/v1/teams/{teamId}/members
  2. Lists all members of a team
  3. Returns user info, role, and join date
  4. Requires: Team membership

  5. Response: 

    {
  "status": "ok",
  "items": [
    {
      "user_id": 1,
      "email": "user@example.com",
      "user_name": "John Doe",
      "role_id": 2,
      "role_name": "Manager",
      "joined_at": "2026-01-13T10:30:00",
      "is_current_user": false
    }
  ]
}

  6. DELETE /api/v1/teams/{teamId}/members/{memberUserId}

  7. Removes a member from the team
  8. Requires: team.manage permission
  9. Protections:
    • Cannot remove yourself
    • Cannot remove the team owner
    • Automatically revokes the removed user's sessions
  10. Response: 
    {
  "status": "ok"
}

Service Functions

list_team_members() - Fetches all team members with join details - Joins User, TeamMember, and Role tables - Marks current user for UI highlighting

remove_team_member() - Validates permissions and ownership - Prevents self-removal and owner removal - Automatically revokes sessions for security

Frontend

New Component: TeamMembersManagement

Location: /home/badeath/cave/mbpanel-main/frontend/src/features/teams/components/TeamMembersManagement.tsx

Features: - ✅ List all team members with avatars - ✅ Display role badges with color coding - ✅ Show join dates formatted - ✅ Inline role change (dropdown) - ✅ Remove member button with confirmation - ✅ Real-time loading states - ✅ Error handling with user feedback - ✅ Refresh button - ✅ Empty state - ✅ Permission-based UI (only managers see actions) - ✅ Cannot remove yourself or the owner - ✅ Automatic session revocation on removal

Props: 

interface TeamMembersManagementProps {
  teamId: number;
  currentUserId: number;
  currentUserPermissions: string[];
  onMemberRemoved?: () => void;
}

Visual Features: - Member avatars with initials - Color-coded role badges (Owner: purple, Manager: blue, Developer: green) - "You" badge for current user - Email display for members with names - Formatted join dates - Disabled states during operations - Hover effects on table rows - Dark mode support

Updated TeamMember Interface

export interface TeamMember {
  user_id: number;
  email: string;
  user_name?: string | null;
  role_id: number;
  role_name: string;
  joined_at: string;
  is_current_user?: boolean;
}

Updated Service Methods

getMembers(teamId: number) - Updated to use new backend endpoint - Returns properly typed members

removeMember(teamId: number, memberUserId: number) - Updated with CSRF token support - Proper error handling

Example Page

Location: /home/badeath/cave/mbpanel-main/frontend/src/app/team-management/page.tsx

Shows both components together: - TeamMembersManagement (list/remove members) - RoleManagement (create/edit roles)

🎨 UI Screenshots (Description)

Team Members Table

┌─────────────────────────────────────────────────────────────┐
│ 👥 Team Members                          🔄 (Refresh)       │
│    3 members                                                 │
├─────────────────────────────────────────────────────────────┤
│ MEMBER              │ ROLE        │ JOINED      │ ACTIONS   │
├─────────────────────┼─────────────┼─────────────┼───────────┤
│ 👤 John Doe    [You]│ 🛡️ Owner    │ Jan 1, 2026 │ --        │
│    john@example.com │             │             │           │
├─────────────────────┼─────────────┼─────────────┼───────────┤
│ 👤 Jane Smith       │ [Manager ▼] │ Jan 5, 2026 │ ❌ Remove │
│    jane@example.com │             │             │           │
├─────────────────────┼─────────────┼─────────────┼───────────┤
│ 👤 Bob Dev          │ [Developer▼]│ Jan 10, 2026│ ❌ Remove │
│    bob@example.com  │             │             │           │
└─────────────────────────────────────────────────────────────┘

📋 Usage Examples

Basic Integration

import { TeamMembersManagement } from '@/features/teams/components';

<TeamMembersManagement
  teamId={user.team_id}
  currentUserId={user.id}
  currentUserPermissions={user.permissions}
/>

With Callback

<TeamMembersManagement
  teamId={user.team_id}
  currentUserId={user.id}
  currentUserPermissions={user.permissions}
  onMemberRemoved={() => {
    console.log('Member was removed - refresh other data if needed');
    // Refresh team stats, etc.
  }}
/>

Full Page Example

'use client';

import { RoleManagement, TeamMembersManagement } from '@/features/teams/components';
import { useAuth } from '@/features/auth/hooks/useAuth';

export default function TeamPage() {
  const { user } = useAuth();

  return (
    <div className="space-y-6">
      {/* Members list with remove capability */}
      <TeamMembersManagement
        teamId={user.team_id}
        currentUserId={user.id}
        currentUserPermissions={user.permissions}
      />

      {/* Role management */}
      <RoleManagement
        teamId={user.team_id}
        currentUserPermissions={user.permissions}
      />
    </div>
  );
}

🔒 Security & Permissions

Backend Security

  1. Cross-Tenant Protection
  2. All endpoints verify user is in the requested team

  3. current_user.team_id must match team_id parameter

  4. Permission Checks

  5. Removing members requires team.manage permission

  6. Viewing members requires team membership only

  7. Owner Protection

  8. Cannot remove the team owner

  9. Owner can only be changed via ownership transfer

  10. Self-Protection

  11. Cannot remove yourself from the team

  12. Must use "leave team" function instead

  13. Session Revocation

  14. When a member is removed, their sessions are immediately revoked
  15. Prevents access with stale JWT tokens

Frontend Security

  1. Permission-Based UI
  2. Actions only visible if user has team.manage

  3. Remove buttons disabled for owner and current user

  4. Confirmation Dialogs

  5. Confirm before removing any member

  6. Error Display

  7. Clear error messages from backend
  8. User-friendly error handling

🔧 Backend Files Modified

Created/Modified:

  • ✅ backend/app/modules/teams/schemas.py - Added TeamMemberRead, TeamMembersListResponse, TeamMemberRemoveResponse
  • ✅ backend/app/modules/teams/service.py - Added list_team_members() and remove_team_member()
  • ✅ backend/app/modules/teams/router.py - Added GET /members and DELETE /members endpoints

📁 Frontend Files Created/Modified

Created:

  • ✅ frontend/src/features/teams/components/TeamMembersManagement.tsx - Main component
  • ✅ frontend/src/app/team-management/page.tsx - Example page

Modified:

  • ✅ frontend/src/features/teams/types/team.types.ts - Updated TeamMember interface
  • ✅ frontend/src/features/teams/services/teamService.ts - Updated getMembers() and removeMember()
  • ✅ frontend/src/features/teams/components/index.ts - Added export

🧪 Testing Guide

Backend Tests (Manual)

  1. List Members 

    curl -X GET http://localhost:8000/api/v1/teams/1/members \
  -H "Cookie: access_token=..." \
  -H "Accept: application/json"

  2. Remove Member 

    curl -X DELETE http://localhost:8000/api/v1/teams/1/members/2 \
  -H "Cookie: access_token=..." \
  -H "X-CSRF-Token: ..." \
  -H "Accept: application/json"

  3. Test Protections

  4. Try removing yourself (should fail)
  5. Try removing owner (should fail)
  6. Try without team.manage permission (should fail)

Frontend Tests

  1. Visual Test
  2. Navigate to /team-management
  3. Verify members load
  4. Check role badges display correctly

  5. Verify "You" badge on current user

  6. Interaction Test

  7. Click role dropdown (should show all roles)
  8. Change a member's role
  9. Click Remove on a member
  10. Confirm dialog appears
  11. Verify member is removed

  12. Check member disappears from list

  13. Permission Test

  14. Login as non-manager
  15. Verify actions are hidden
  16. Login as manager
  17. Verify actions are visible

🎯 Key Features Implemented

Member Display

  • ✅ Avatar with initials
  • ✅ Name and email display
  • ✅ Role badge with color coding
  • ✅ Join date formatting
  • ✅ "You" indicator
  • ✅ Member count in header

Member Management

  • ✅ List all team members
  • ✅ Change member roles (inline dropdown)
  • ✅ Remove members with confirmation
  • ✅ Refresh members list
  • ✅ Loading states during operations
  • ✅ Error handling with messages

Security

  • ✅ Cannot remove yourself
  • ✅ Cannot remove owner
  • ✅ Permission-based UI
  • ✅ Session revocation on removal
  • ✅ CSRF protection

UX Enhancements

  • ✅ Empty state message
  • ✅ Loading spinner
  • ✅ Disabled states during operations
  • ✅ Hover effects
  • ✅ Dark mode support
  • ✅ Responsive design
  • ✅ Accessible markup

🚀 Next Steps

  1. Add Member Invitation to Component

  2. Could add invite form directly in TeamMembersManagement

  3. Add Bulk Actions

  4. Select multiple members
  5. Bulk role assignment

  6. Bulk removal

  7. Add Member Activity

  8. Last seen timestamp

  9. Activity indicators

  10. Add Search/Filter

  11. Search by name/email

  12. Filter by role

  13. Add Pagination

  14. For teams with many members
  15. Show members per page

❓ FAQ

Q: Can a user remove themselves? A: No, the backend prevents self-removal. Users should use a "Leave Team" function instead.

Q: What happens when a member is removed? A: Their team membership is deleted, and all their active sessions are revoked immediately.

Q: Can the owner be removed? A: No, ownership must be transferred first via the ownership transfer flow.

Q: Who can see the members list? A: Any team member can view the list, but only users with team.manage permission can remove members.

Q: Can I change multiple roles at once? A: Currently no, but this could be added as a bulk action feature.

Q: What if I remove someone by mistake? A: They need to be re-invited to the team. Consider adding an "undo" feature in the future.