> ## 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.

# Users & Members

> Managing all tontine users - members who participate in savings/loans and staff who operate the system

## Understanding Tontine Users

Your tontine has two types of people with access to Agatabo:

1. **Members** - People who save money and may take loans (the core participants)
2. **Staff** - People who operate the system (treasurers, accountants, administrators) but don't necessarily save or borrow

Both are "users" in the system, but they have different roles and permissions.

## User vs Member

<Tabs>
  <Tab title="User (General)">
    **Any person with login credentials to your tontine**

    * Has login credentials (email or phone number)
    * Has one or more assigned roles
    * Can log in and perform permitted actions
    * May or may not be a member
    * Email is optional; phone number is required

    **Examples**: Treasurer, Accountant, Administrator, Loan Officer, Manager, Member
  </Tab>

  <Tab title="Member (Specific)">
    **A user who participates in savings and loans**

    * Has the "Member" role assigned
    * Contributes savings to the tontine
    * Can apply for and receive loans
    * Has a savings ledger account
    * Receives dividends when distributed
    * May also have other roles (e.g., Treasurer + Member)

    **Key point**: All members are users, but not all users are members. Your treasurer might just be staff (not a member), or they might be both staff AND a member.
  </Tab>
</Tabs>

## User Lifecycle

<Steps>
  <Step title="Invitation">
    Administrator creates user and sends invitation (via email, SMS, or manual link sharing)
  </Step>

  <Step title="Account Activation">
    Person clicks activation link and sets password
  </Step>

  <Step title="Active User">
    Can log in with email or phone number and perform assigned tasks
  </Step>

  <Step title="Role Updates">
    Administrator adds/removes roles as needed
  </Step>

  <Step title="Deactivation (optional)">
    User leaves tontine, account disabled
  </Step>
</Steps>

## Common Operations

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

  <Card title="Managing Users" icon="users-gear" href="/tontines/organization-users/managing-users">
    Edit info, deactivate accounts, update roles
  </Card>

  <Card title="Roles & Permissions" icon="user-tag" href="/tontines/organization-users/roles">
    Understand roles and what each can do
  </Card>

  <Card title="Viewing User Details" icon="address-card" href="/tontines/organization-users/viewing-member-details">
    Access user profiles and account history
  </Card>
</CardGroup>

## Default Roles

Your tontine comes with two default roles:

| Role              | Purpose           | Typical Permissions                       |
| ----------------- | ----------------- | ----------------------------------------- |
| **Member**        | Saves and borrows | View own savings, view own loans          |
| **Administrator** | Manages system    | All permissions including user management |

Administrators can create additional custom roles as needed (Treasurer, Accountant, Loan Officer, Manager, etc.) with specific permissions configured per role.

<Note>
  **Common pattern**: In many tontines, the treasurer and accountant are also members (they save and borrow). In this case, they would have multiple roles assigned: "Member + Treasurer" or "Member + Accountant". Other tontines hire staff who are NOT members - they just operate the system.
</Note>

[Detailed role information →](/organization-users/member-roles)

## Organization User Information

### Basic Information

* **Name**: Full name (single field)
* **Account Number**: Auto-generated unique identifier
* **Email**: Optional - used for login and notifications if provided
* **Phone**: Required - mobile number for SMS notifications
* **Join Date**: Date the user joined the organization

### Financial Information (for Members)

* **Savings Balance**: Total deposits minus withdrawals
* **Active Loans**: Current outstanding loans
* **Loan History**: Past loans and repayment status
* **Entry Fees**: Joining fees and payments
* **Dividend Allocations**: Share of distributed profits

[View user details guide →](/tontines/organization-users/viewing-member-details)

## User Status

| Status       | Meaning             | Can Log In?             | Can Access Organization?  |
| ------------ | ------------------- | ----------------------- | ------------------------- |
| **Active**   | Account enabled     | ✅ Yes (if password set) | ✅ Yes                     |
| **Inactive** | Account deactivated | ✅ Yes (if password set) | ❌ No (permissions denied) |

<Note>
  **How it works:**

  * An inactive user can technically log in but won't be able to access any organization features
  * Permissions are only resolved for active users (`isActive = true`)
  * To fully prevent access, deactivate the organization user

  **Invitation status:** Tracked separately with values `PENDING`, `ACCEPTED`, `REVOKED`
</Note>

## Permissions System

Agatabo uses **role-based access control** (RBAC):

### Permission Format

Permissions use the format: `resource:action`

**Examples**:

* `organization_users:read` - Can view organization users
* `organization_users:write` - Can create/edit organization users
* `savings:read` - Can view savings data
* `savings:write` - Can record deposits
* `loans:read` - Can view loans
* `loans:write` - Can create loans

### Permission Scopes

Each permission can be scoped to control access level:

**SELF scope**: User can only access their own data

* A member with `savings:read` (SELF scope) can only view their own savings

**ANY scope**: User can access all organization data

* A treasurer with `savings:write` (ANY scope) can record deposits for any member

[Full permissions matrix →](/reference/permissions-matrix)

## Member Management Best Practices

<Note>
  **User management tips:**

  * Verify phone numbers before sending invitations (phone is required)
  * Email is optional but recommended for login and notifications
  * Assign minimum necessary permissions (principle of least privilege)
  * Review user permissions quarterly
  * Deactivate former staff immediately
  * Use consistent naming conventions
  * Note that Name, Phone, and Email cannot be easily changed after creation
</Note>

## Common Scenarios

### Adding a New Organization User

<Steps>
  <Step title="Collect user information">
    Name, phone (required), email (optional), join date
  </Step>

  <Step title="Add to Agatabo">
    Organization Users → Click "Add Organization User"
  </Step>

  <Step title="Fill in form">
    Complete Name, Join Date, Phone, and optional Email fields
  </Step>

  <Step title="Choose invitation option">
    Toggle "Send Invitation" on/off (sends invite via email or SMS)
  </Step>

  <Step title="User activates account">
    User clicks invitation link, sets password, and is automatically logged in
  </Step>

  <Step title="Assign roles">
    After creation, navigate to user's Roles tab to assign member or other roles
  </Step>
</Steps>

[Full workflow →](/workflows/new-member-onboarding)

### Adding a Role to an Existing User

<Steps>
  <Step title="Navigate to Organization Users">
    Find the user
  </Step>

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

  <Step title="Go to Roles tab">
    Click the "Roles" tab
  </Step>

  <Step title="Click Assign role">
    Opens role assignment dialog
  </Step>

  <Step title="Select role from dropdown">
    Choose the role to assign (e.g., Treasurer, Member)
  </Step>

  <Step title="Save changes">
    User now has the additional role and its permissions
  </Step>
</Steps>

### Deactivating a User

<Steps>
  <Step title="Remove all roles">
    User must have no assigned roles before deactivation
  </Step>

  <Step title="Navigate to user details">
    Organization Users → Click user name
  </Step>

  <Step title="Click Deactivate">
    In Account Actions section, click "Deactivate Organization User"
  </Step>

  <Step title="Confirm deactivation">
    Confirm in the dialog
  </Step>

  <Step title="User account disabled">
    User can no longer log in; data retained for audit purposes
  </Step>
</Steps>

## Integration with Other Features

### Savings

Members with savings have **savings ledger accounts**:

* Tracks deposit balance
* Shows transaction history
* Appears on balance sheet as liability

### Loans

Loans are created for members by loan officers:

* Loan history tracked per member
* Guarantors can be other organization users with member role
* Loan securities can include savings balances

### Dividends

Members can receive dividend allocations from dividend pools:

* Distribution methods: equal or by contribution
* Administrators create dividend pools and distribute to members

### Reports

Tontine users appear in the following reports:

* Balance Sheet
* Profit & Loss
* Shares Report (members only)
* Loans Outstanding (members only)

## Security and Privacy

<Warning>
  **Data protection:**

  * Member financial data is confidential
  * Only users with appropriate permissions can view data
  * Members can only view their own data (unless given additional permissions)
  * Staff with appropriate roles can view all member data
  * Email and phone numbers are used for login and notifications
</Warning>

## Need Help?

<CardGroup cols={2}>
  <Card title="Inviting Users" icon="user-plus" href="/tontines/organization-users/inviting-users">
    Step-by-step invitation guide
  </Card>

  <Card title="Managing Users" icon="users-gear" href="/tontines/organization-users/managing-users">
    Edit, deactivate, update roles
  </Card>

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

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