> ## Documentation Index
> Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# User Management

> Manage all users across the platform with full CRUD operations and impersonation capabilities

## Overview

The User Management module provides administrators with complete control over all user accounts in the platform. View, create, edit, and delete users across all roles (Members, Client Staff, Sponsors) from a centralized datagrid.

## User Stories

### US-ADMIN-001: User Management Datagrid

**As an** admin\
**I want to** have a User management datagrid\
**So that** I can see all the users in my platform and add, edit, and delete them

#### Acceptance Criteria

<AccordionGroup>
  <Accordion title="View Users">
    * Display all users in a searchable, sortable datagrid
    * Show columns: Name, Email, Role, Status, Organization, Last Login, Created Date
    * Support pagination (default 25 per page)
    * Filter by role (Member, Client User, Client Admin, Sponsor, Platform Admin)
    * Filter by status (Active, Inactive, Suspended, Pending)
    * Filter by organization/tenant
    * Search by name or email (partial match)
    * Export filtered results to CSV
  </Accordion>

  <Accordion title="Create User">
    * Click "Add User" button to open creation form
    * Required fields: First Name, Last Name, Email, Role
    * Optional fields: Phone, Organization, Initial Password
    * Auto-generate password option with email notification
    * Validate email uniqueness across platform
    * Assign user to specific organization/tenant
    * Set initial status (Active or Pending Verification)
    * Send welcome email with login instructions
  </Accordion>

  <Accordion title="Edit User">
    * Click row or edit icon to open user detail/edit view
    * Edit all user profile fields
    * Change user role (with confirmation for privilege changes)
    * Change user status (Active, Inactive, Suspended)
    * Reset password and send reset email
    * View user activity log
    * View user's organization memberships
    * Cannot edit own role or status (prevent self-lockout)
  </Accordion>

  <Accordion title="Delete User">
    * Soft delete with confirmation dialog
    * Show warning if user has associated data (memberships, enrollments, etc.)
    * Option to transfer ownership of data before deletion
    * Retain audit trail of deleted user actions
    * Cannot delete own account
    * Permanently delete option (requires additional confirmation)
  </Accordion>
</AccordionGroup>

***

### US-ADMIN-002: User Impersonation

**As an** admin\
**I want to** be able to impersonate a user\
**So that** I can see what they can see and aid them in troubleshooting

#### Acceptance Criteria

<AccordionGroup>
  <Accordion title="Initiate Impersonation">
    * Click "Impersonate" button on user row or detail view
    * Confirmation dialog showing target user details
    * Select target portal (auto-detected based on user role):
      * Member Portal for members
      * Client Portal for client users/admins
      * Sponsor Portal for sponsors
    * Generate temporary impersonation token (15-minute expiry)
    * Redirect to target portal with impersonation session
  </Accordion>

  <Accordion title="Impersonation Session">
    * Persistent banner at top of screen: "You are impersonating \[User Name] - Exit"
    * Banner shows remaining session time
    * Full read access to user's view
    * Restricted write access (configurable):
      * Default: Read-only mode
      * Optional: Allow actions on behalf of user (logged)
    * All actions logged with "impersonated by \[Admin]" notation
    * Cannot impersonate another user while impersonating
  </Accordion>

  <Accordion title="Exit Impersonation">
    * Click "Exit" button in impersonation banner
    * Automatic exit after session timeout (15 minutes)
    * Return to Admin Portal user management screen
    * Clear impersonation token and session
    * Log impersonation session end time and duration
  </Accordion>

  <Accordion title="Audit & Security">
    * Log all impersonation sessions:
      * Admin who initiated
      * Target user
      * Start time, end time, duration
      * Actions performed during session
    * Require MFA before impersonation (if enabled)
    * Email notification to user when impersonated (configurable)
    * Cannot impersonate other Platform Admins
    * Rate limit: Max 10 impersonation sessions per hour per admin
  </Accordion>
</AccordionGroup>

***

## Datagrid Columns

| Column       | Type     | Sortable | Filterable       | Description                          |
| ------------ | -------- | -------- | ---------------- | ------------------------------------ |
| Name         | Text     | Yes      | Yes (search)     | Full name (First + Last)             |
| Email        | Text     | Yes      | Yes (search)     | User email address                   |
| Role         | Badge    | Yes      | Yes (dropdown)   | User role with color coding          |
| Organization | Text     | Yes      | Yes (dropdown)   | Assigned organization/tenant         |
| Status       | Badge    | Yes      | Yes (dropdown)   | Active, Inactive, Suspended, Pending |
| Last Login   | DateTime | Yes      | Yes (date range) | Last successful login timestamp      |
| Created      | DateTime | Yes      | Yes (date range) | Account creation date                |
| Actions      | Buttons  | No       | No               | Edit, Impersonate, Delete            |

## Role Definitions

| Role                  | Portal Access              | Description                                                       |
| --------------------- | -------------------------- | ----------------------------------------------------------------- |
| `ROLE_MEMBER`         | Member Portal              | Standard association member                                       |
| `ROLE_CLIENT_USER`    | Member + Client Portal     | Organization staff (limited permissions)                          |
| `ROLE_CLIENT_ADMIN`   | Member + Client Portal     | Organization admin (full permissions)                             |
| `ROLE_SPONSOR_USER`   | Member + Sponsor Portal    | Sponsor user (campaign contributor; limited admin rights)         |
| `ROLE_SPONSOR_ADMIN`  | Member + Sponsor Portal    | Sponsor admin (primary sponsor contact; full sponsor permissions) |
| `ROLE_PLATFORM_ADMIN` | All Portals + Admin Portal | Platform administrator                                            |

## Status Definitions

| Status    | Description                              | Can Login |
| --------- | ---------------------------------------- | --------- |
| Active    | Normal active account                    | Yes       |
| Inactive  | Manually deactivated                     | No        |
| Suspended | Temporarily suspended (policy violation) | No        |
| Pending   | Awaiting email verification              | No        |

## API Endpoints

```
GET    /api/admin/users              # List all users (paginated)
GET    /api/admin/users/{id}         # Get user details
POST   /api/admin/users              # Create user
PUT    /api/admin/users/{id}         # Update user
DELETE /api/admin/users/{id}         # Soft delete user
POST   /api/admin/users/{id}/impersonate    # Start impersonation
DELETE /api/admin/impersonate        # End impersonation
GET    /api/admin/users/{id}/activity       # Get user activity log
POST   /api/admin/users/{id}/reset-password # Send password reset
```

## Security Considerations

<Warning>
  Impersonation is a powerful feature. All impersonation sessions are logged and auditable. Misuse may result in access revocation.
</Warning>

* All admin actions require valid JWT with `ROLE_PLATFORM_ADMIN` role
* MFA required for sensitive operations (impersonation, deletion)
* Impersonation tokens are short-lived (15 minutes)
* Cannot impersonate users with equal or higher privilege level
* All actions during impersonation are attributed to the admin in audit logs