👥 User Management APIs
Organization user lifecycle, roles, and permissions
Executive Summary
User Management APIs provide full lifecycle management for organization users including creation, role assignment, status management, and deletion. All operations are scoped to the Admin's organization via JWT claims.
✅ Full CRUD
Create, read, update, delete users
Create, read, update, delete users
✅ Role Assignment
Assign roles, custom permissions
Assign roles, custom permissions
✅ Bulk Operations
Import, export, mass actions
Import, export, mass actions
⚠️ No Hierarchy
Flat user list, no reporting structure
Flat user list, no reporting structure
📊 API Inventory
| Controller | Route | Endpoints | Authorization | Features |
|---|---|---|---|---|
| UsersManagementController | /api/usersmanagement | 8 | HasPermission | CRUD + Search + Bulk |
| RoleManagementController | /api/rolemanagement | 10 | HasPermission | Roles + Assignments |
🔌 User Management Endpoints
User CRUD
GET
/api/usersmanagement
List users in organization with pagination, filtering, sorting.
HasPermission:Users.View Existing
Query: ?page=1&pageSize=20&search=john&role=User&status=Active
GET
/api/usersmanagement/{id}
Get user details including profile, roles, permissions, last activity.
HasPermission:Users.View Existing
POST
/api/usersmanagement
Create new user. Auto-sends invitation email with set-password link.
HasPermission:Users.Create Existing
PUT
/api/usersmanagement/{id}
Update user profile, status, role. Cannot modify email (unique constraint).
HasPermission:Users.Edit Existing
Role Management
GET
/api/rolemanagement
List roles available in organization (system + custom).
HasPermission:Roles.View Existing
POST
/api/rolemanagement/{userId}/assign
Assign role to user. Removes previous role assignment.
HasPermission:Roles.Assign Existing
POST
/api/rolemanagement/bulk-assign
Bulk assign role to multiple users.
HasPermission:Roles.BulkAssign Existing
🛡️ RBAC Architecture
RBAC Implementation Flow
═══════════════════════════════════════════════════════════════════════════════
User Request: GET /api/usersmanagement
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ [Authorize] Attribute │
│ (JWT Validation) │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ [HasPermission("Users.View")] Attribute │
│ │
│ 1. Extract UserId from JWT │
│ 2. Extract OrganizationId from JWT │
│ 3. Call IRoleManagementService.HasPermissionAsync() │
│ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Permission Resolution Flow │ │
│ │ │ │
│ │ Step 1: Get User's Roles │ │
│ │ SELECT r.* FROM Roles r │ │
│ │ JOIN UserRoles ur ON ur.RoleId = r.Id │ │
│ │ WHERE ur.UserId = @userId │ │
│ │ │ │
│ │ Step 2: Get Role Permissions │ │
│ │ SELECT p.Name FROM Permissions p │ │
│ │ JOIN RolePermissions rp ON rp.PermissionId = p.Id │ │
│ │ WHERE rp.RoleId IN (@roleIds) │ │
│ │ │ │
│ │ Step 3: Check Required Permission │ │
│ │ IF "Users.View" IN permissions │ │
│ │ RETURN TRUE │ │
│ │ ELSE │ │
│ │ RETURN FALSE → 403 Forbidden │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
│
▼ (if authorized)
┌─────────────────────────────────────────────────────────────────────┐
│ UsersManagementController.GetUsers() │
│ │
│ // Auto-scope to organization │
│ var orgId = GetCurrentOrganizationId(); // From JWT │
│ var users = await _userService.GetByOrganizationAsync(orgId); │
│ │
└─────────────────────────────────────────────────────────────────────┘
👥 System Roles Hierarchy
Role Hierarchy & Permissions
═══════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────┐
│ ROLE HIERARCHY │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ SuperAdmin │ │
│ │ (Role Level: 100, System Role) │ │
│ │ Permissions: ["*"] // All permissions │ │
│ │ Scope: All Organizations │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ Inherits all + can manage platform │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Admin │ │
│ │ (Role Level: 50, System Role) │ │
│ │ Permissions: │ │
│ │ ["Users.View", "Users.Create", "Users.Edit", │ │
│ │ "Users.Delete", "Roles.Assign", "Analytics.View",│ │
│ │ "Reports.View", "Exports.Create", │ │
│ │ "Organization.Edit", "Billing.View"] │ │
│ │ Scope: Own Organization Only │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ Can manage org-level resources │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Manager │ │
│ │ (Role Level: 30, System Role) │ │
│ │ Permissions: │ │
│ │ ["Users.View", "Team.View", "Analytics.View", │ │
│ │ "Reports.View", "Exports.Create"] │ │
│ │ Scope: Team Members (future: hierarchy-based) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ User │ │
│ │ (Role Level: 10, System Role) │ │
│ │ Permissions: │ │
│ │ ["Profile.View", "Profile.Edit", │ │
│ │ "Analytics.Own", "Sessions.Own"] │ │
│ │ Scope: Self Only │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ Custom Roles: │
│ • Admins can create custom roles with subset of permissions │
│ • Custom roles cannot exceed Admin permission level │
│ • Role Level enforces hierarchy (higher level = more access) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
🗄️ Database Schema
| Table | Purpose | Key Relationships |
|---|---|---|
| Users | User accounts | FK OrganizationId, 1:N Sessions, Devices |
| Roles | Role definitions | N:1 Organization (null=system), 1:N UserRoles |
| UserRoles | User-role assignments | FK UserId, FK RoleId |
| Permissions | Permission definitions | 1:N RolePermissions |
| RolePermissions | Role-permission mappings | FK RoleId, FK PermissionId |
⚠️ Security Concerns
No Hierarchy
All users flat in organization. No manager-reporting relationship for scoped access.
Role Level Bypass
Custom roles can potentially be created with high level. Needs validation.
Org Isolation
Users cannot access other organizations' data. Enforced at middleware + repository layers.