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

# Managing Users

> Update roles and manage account status for members and staff

## Overview

Managing users involves changing roles and handling account status changes. This guide covers all user management operations after initial invitation - for both members and staff.

## Managing Roles

Roles determine what permissions a user has in your organization.

### Adding a Role

<Steps>
  <Step title="Open user details">
    Click on user name
  </Step>

  <Step title="Navigate to Roles tab">
    Or click **Manage Roles** button
  </Step>

  <Step title="Click 'Assign Role'">
    Opens role assignment form
  </Step>

  <Step title="Select role to add">
    Choose from available roles (Member, Treasurer, etc.)
  </Step>

  <Step title="Optionally set assignment date">
    Backdate the role assignment if needed
  </Step>

  <Step title="Save changes">
    New permissions take effect **immediately**
  </Step>
</Steps>

<Note>
  **Special case - Member role**: When you assign the "Member" role, a savings ledger account is automatically created for the user.
</Note>

<Warning>
  **Administrator role**: The Administrator role cannot be assigned through the normal role assignment process. Contact a system administrator to use the special admin assignment function.
</Warning>

### Removing a Role

<Steps>
  <Step title="Open user details">
    Click on user name
  </Step>

  <Step title="Navigate to Roles tab">
    View current roles
  </Step>

  <Step title="Click 'Remove' on the role">
    Or uncheck the role to remove
  </Step>

  <Step title="Confirm removal">
    Verify user should lose these permissions
  </Step>

  <Step title="Save changes">
    Permissions revoked **immediately**
  </Step>
</Steps>

<Warning>
  **Removing the Member role**: If you remove the Member role:

  * User can no longer participate in savings and loans
  * Their savings ledger account is NOT automatically deleted
  * Only do this for staff who are not members
</Warning>

<Warning>
  **Administrator role**: The Administrator role cannot be removed through the normal role removal process. Contact a system administrator.
</Warning>

### Permission Required

Role management requires the **`organization_user_roles:assign`** permission (separate from user invitation permission).

## Deactivating Accounts

Deactivating removes a user's access to the organization while preserving all their data and transaction history.

### When to Deactivate

* Member leaves the organization (and has financial history)
* Staff member's employment ends
* Security concern requires immediate access removal
* User should lose access but data must be preserved

<Warning>
  **Before you can deactivate**: You must **remove ALL roles first**. The system prevents deactivation of users who still have assigned roles.
</Warning>

### Deactivation Process

<Steps>
  <Step title="Remove all roles">
    Navigate to user's Roles tab → Remove all assigned roles (Member, Treasurer, etc.)
  </Step>

  <Step title="Navigate to user details">
    Click on user name
  </Step>

  <Step title="Click 'Deactivate Account'">
    Or change status to Inactive
  </Step>

  <Step title="Confirm deactivation">
    Access restrictions apply immediately
  </Step>
</Steps>

### What Happens When Deactivated

**Access:**

* ✅ User CAN still log in to Agatabo
* ❌ User CANNOT access organization resources
* ❌ User CANNOT perform any operations
* User sees "Deactivated" status when attempting to access

**Data:**

* ✅ All historical data preserved
* ✅ Appears in reports for historical periods
* ✅ Transaction history unchanged
* ✅ Savings balance preserved

**Reversibility:**

* ✅ Can be reactivated at any time
* No data loss occurs

## Reactivating Accounts

<Steps>
  <Step title="Navigate to Organization Users">
    Filter by Inactive status (if available)
  </Step>

  <Step title="Find deactivated user">
    Click on user name
  </Step>

  <Step title="Click 'Reactivate Account'">
    Or change status to Active
  </Step>

  <Step title="Assign appropriate roles">
    Navigate to Roles tab and re-assign necessary roles
  </Step>

  <Step title="Confirm reactivation">
    User can access organization again immediately
  </Step>
</Steps>

<Note>
  **Reactivation restores access**: The user can immediately access the organization again, but you must re-assign their roles manually.
</Note>

## Deleting Users

Deleting completely removes a user from the organization. **This is only possible for users with NO financial history.**

### When You Can Delete

* User was invited but never activated
* User activated but has no transactions
* User has no entry fee recorded
* Duplicate account created by error (before any activity)

### When You CANNOT Delete

❌ User has ANY of the following:

* Savings deposits
* Loan transactions
* Dividend distributions
* Entry fee recorded
* Any other financial transactions

<Warning>
  **Financial history is immutable**: Once a user has ANY financial activity, they cannot be deleted. You must deactivate them instead. This preserves audit trails and financial integrity.
</Warning>

### Deletion Process

<Steps>
  <Step title="Verify no financial history">
    Confirm user has no transactions or entry fee
  </Step>

  <Step title="Navigate to user details">
    Click on user name
  </Step>

  <Step title="Click 'Delete User'">
    Option only available if no financial history
  </Step>

  <Step title="Confirm deletion">
    User and all related data removed permanently
  </Step>
</Steps>

### What Gets Deleted

When you delete a user:

* ✅ Organization user record
* ✅ All role assignments
* ✅ All invitations
* ✅ Savings ledger account (if exists and empty)
* ✅ User record (if this was their only organization)
* ✅ User sessions

<Warning>
  **Deletion is permanent**: Unlike deactivation, deletion cannot be reversed. Only delete when you're certain the user should never have existed in the system.
</Warning>

## Delete vs Deactivate

| Operation      | Use When               | Reversible? | Data Preserved? | Financial History? |
| -------------- | ---------------------- | ----------- | --------------- | ------------------ |
| **Delete**     | No financial activity  | ❌ No        | ❌ No            | Not allowed        |
| **Deactivate** | Has financial activity | ✅ Yes       | ✅ Yes           | Required           |

**Business Rule**:

* If user has transactions/entry fee → **Must deactivate** (delete blocked)
* If user has no activity → **Should delete** (clean removal)

## Resending Invitations

If a user's activation link expired or they never received it:

<Steps>
  <Step title="Navigate to Organization Users">
    Find users with Pending status
  </Step>

  <Step title="Find pending user">
    Click on user name
  </Step>

  <Step title="Click 'Resend Invitation'">
    Generates new activation link
  </Step>

  <Step title="New invitation sent">
    User receives fresh invitation (72-hour expiry)
  </Step>
</Steps>

### How Resending Works

1. **Revokes all pending invitations** for this user
2. **Creates new invitation** with fresh 72-hour expiration
3. **Sends automatically** (if email/SMS enabled) or provides manual link
4. **Only one active invitation** at a time per user

<Note>
  **Cannot resend after acceptance**: Once a user has activated their account, you cannot resend invitations. They should use the password reset process if they can't log in.
</Note>

## Resetting Passwords

If a user forgets their password:

<Steps>
  <Step title="User clicks 'Forgot Password'">
    On the login page
  </Step>

  <Step title="Enters email address">
    System sends reset link
  </Step>

  <Step title="Clicks reset link">
    Opens password reset page
  </Step>

  <Step title="Sets new password">
    Must meet security requirements
  </Step>
</Steps>

<Note>
  **Self-service only**: Administrators cannot see or reset user passwords directly. Users must use the self-service password reset process for security.
</Note>

## Permissions Required

| Operation                           | Permission Needed                |
| ----------------------------------- | -------------------------------- |
| Edit user info (name, email, phone) | `organization_users:write`       |
| Assign/remove roles                 | `organization_user_roles:assign` |
| Deactivate/reactivate users         | `organization_users:write`       |
| Delete users                        | `organization_users:write`       |
| Resend invitations                  | `organization_users:write`       |

## Best Practices

<Note>
  **User management tips:**

  * **Remove roles before deactivation** - required by the system
  * **Use delete only for mistakes** - deactivate for legitimate exits
  * **Verify financial balances** before deactivating members with transactions
  * **Document role changes** - keep notes on why roles were added/removed
  * **Test email/phone changes** - verify user can still log in after updates
  * **Regular audits** - review active vs inactive users quarterly
  * **Keep contact info current** - update phone/email promptly for notifications
  * **Consider impact of email changes** - affects all organizations user belongs to
</Note>

## Need Help?

<CardGroup cols={2}>
  <Card title="Inviting Users" icon="user-plus" href="/tontines/organization-users/inviting-users">
    Add new organization users
  </Card>

  <Card title="Member Roles" icon="sitemap" href="/tontines/organization-users/roles">
    Understanding roles and permissions
  </Card>

  <Card title="Viewing Member Details" icon="address-card" href="/tontines/organization-users/viewing-member-details">
    Access member account information
  </Card>

  <Card title="Permissions Matrix" icon="shield" href="/reference/permissions-matrix">
    Full permission reference
  </Card>
</CardGroup>