Quick Start: Adding Role Management to Your Team Settings

This guide shows you how to quickly add the role management UI to your team settings page.

Step 1: Import the Component

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

Step 2: Add to Your Page

'use client';

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

export default function TeamRolesPage() {
  // Get user from your auth system
  // This is just an example - adjust to your auth implementation
  const { user } = useAuth();

  if (!user) return <div>Loading...</div>;

  return (
    <div className="container mx-auto p-6">
      <RoleManagement
        teamId={user.team_id}
        currentUserPermissions={user.permissions}
      />
    </div>
  );
}

Step 3: Verify Backend is Running

Make sure these endpoints are accessible: - GET /api/v1/rbac/permissions - Returns all available permissions - GET /api/v1/rbac/teams/{teamId}/roles - Returns team roles - POST /api/v1/rbac/teams/{teamId}/roles - Creates new role - PUT /api/v1/rbac/teams/{teamId}/roles/{roleId}/permissions - Updates permissions - DELETE /api/v1/rbac/teams/{teamId}/roles/{roleId} - Deletes role

Step 4: Test the UI

1. View Roles - You should see Owner, Manager, and Developer roles by default
2. Hover Over a Role - A tooltip should appear showing all permissions
3. Create Custom Role (if you have team.manage permission):
4. Click "Create Custom Role"
5. Fill in name and description
6. Select permissions from checkboxes
7. Click "Create Role"
8. Edit Permissions:
9. Click "Edit Permissions" on any editable role
10. Modify the permission checkboxes
11. Click "Update Permissions"
12. Delete Role:
13. Click "Delete" on any custom role
14. Confirm the deletion

Troubleshooting

"Failed to fetch permissions"

• Check that the backend is running
• Verify the API URL is correct in your environment variables
• Check browser console for CORS issues

"Failed to create role"

• Ensure CSRF token is being sent correctly
• Check that user has team.manage permission
• Verify role name doesn't already exist

Tooltips not showing

• Check that z-index is correct (component uses z-50)
• Verify hover events are working (no CSS blocking pointer events)

Permissions not updating after edit

• Check browser console for errors
• Backend should be revoking sessions - verify this is working
• User may need to log out and back in

Customization

Styling

The component uses Tailwind CSS classes. To customize:

// Adjust colors by modifying the component or wrapping in a div
<div className="custom-role-management">
  <RoleManagement {...props} />
</div>

Adding New Permissions

1. Create an Alembic migration:

   def upgrade():
       op.execute(
           sa.text("""
               INSERT INTO permissions (slug, description)
               VALUES ('reports.view', 'View reports')
               ON CONFLICT (slug) DO NOTHING
           """)
       )
   

2. Run migration: alembic upgrade head

3. New permission will automatically appear in the UI

Custom Default Roles

To change default role permissions, edit: backend/app/modules/auth/service.py → _ensure_default_roles() method

Next Steps

• Add role assignment to team member management
• Create role-based navigation/feature flags
• Add audit logging for permission changes
• Implement role templates for quick setup

Need Help?

See the full documentation: - /docs/RBAC_IMPLEMENTATION_SUMMARY.md - Complete feature overview - /docs/RBAC_VISUAL_GUIDE.md - Visual diagrams - /docs/architecture/team_management.md - Technical design