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

# Roles

> Understanding roles, permissions, and access control in Agatabo

## Overview

Roles determine what users can do in Agatabo. Each role has specific permissions that control access to features and data.

Agatabo provides **2 default roles** (Admin and Member) and supports creating **custom roles** for your organization's specific needs.

## Default Roles

### Administrator

**Purpose**: Full system access and organization management

**Permissions**: All permissions with ANY scope (full access to everything)

**Can do**:

* Manage all users and roles
* Record all transactions (deposits, loans, expenses)
* Access all reports and financial data
* Configure organization settings
* View audit logs
* Close accounting periods
* Manage bank accounts, reserves, and dividends

**Protection**: Cannot be deleted (protected role)

**Use when**: Person manages the organization and needs complete control

***

### Member

**Purpose**: View personal financial information

**Default permissions** (SELF scope only):

* `organization_users:read` (SELF) - View own profile
* `savings:read` (SELF) - View own savings balance and deposits
* `loans:read` (SELF) - View own loans and payments
* `dividends:read` (SELF) - View own dividend distributions

**Cannot do** (by default):

* View other members' data
* Record transactions
* Access administrative features
* Modify anything

**Protection**: Cannot be deleted (protected role)

**Customization**: Permissions can be modified by administrators

**Use when**: Person participates in savings and loans

<Note>
  **Member role is customizable**: Unlike the Admin role, the Member role's permissions can be adjusted by your administrator to fit your organization's needs.
</Note>

## Custom Roles

Your organization can create additional roles beyond Admin and Member.

**Common custom roles**:

* **Treasurer**: Records deposits and manages cash
* **Loan Officer**: Creates and manages loans
* **Accountant**: Generates reports and manages accounting
* **Secretary**: Manages communications and records

**How custom roles work**:

* Created by administrators with `organization_user_roles:assign` permission
* Can be fully customized (any combination of permissions)
* Can be edited or deleted (not protected)
* Combine with other roles for flexible access control

<Note>
  **Ask your administrator**: Check with your organization's administrator to see what custom roles exist and what permissions they have.
</Note>

## Permission Scopes

Permissions can have different scopes that control the extent of access:

### SELF Scope

User can only access their own data.

**Example**: Member with `savings:read` (SELF scope)

* Can view their own savings deposits
* Cannot view other members' savings

**Use when**: Limiting access to personal information only

### ANY Scope

User can access all organization data.

**Example**: Treasurer with `savings:read` (ANY scope)

* Can view all members' savings deposits
* Useful for operational roles

**Use when**: Role requires organization-wide visibility

## Multiple Roles

Users can have multiple roles simultaneously, and permissions are combined.

**Example**: User with both Member + Custom Treasurer Role

* Views own savings (from Member role)
* Records deposits for all members (from Treasurer role)
* Common in small organizations where members also operate the system

### Permission Combination Rules

When a user has multiple roles with overlapping permissions:

**Most permissive scope wins**:

* If one role grants `savings:read` (SELF) and another grants `savings:read` (ANY)
* User gets `savings:read` (ANY) - the broader scope

**Permissions are additive**:

* User gets ALL permissions from ALL assigned roles
* More roles = more permissions

## Available Permissions

Here are the main permission categories in Agatabo:

| Permission                    | What It Controls                          |
| ----------------------------- | ----------------------------------------- |
| **organization\_users**       | View and manage users                     |
| **savings**                   | View and record deposits/withdrawals      |
| **loans**                     | View, create, and manage loans            |
| **expenses**                  | View and record expenses                  |
| **assets**                    | View and manage fixed assets              |
| **bank\_accounts**            | View and manage cash/bank accounts        |
| **reserves**                  | View and manage reserves                  |
| **dividends**                 | View and distribute dividends             |
| **reports**                   | Generate financial reports                |
| **settings**                  | Configure organization settings           |
| **ledger**                    | Access general ledger and journal entries |
| **organization\_user\_roles** | Manage roles and permissions              |
| **periods**                   | Close accounting periods                  |
| **audit\_logs**               | View system audit trail                   |

Each permission has `:read`, `:write`, or specialized actions (`:approve`, `:modify`, `:assign`, `:close`).

## Checking Your Permissions

To see what you can access:

1. **Menu visibility**: You only see features you have permission to use
2. **Try an action**: You'll get an error if you lack the required permission
3. **Contact administrator**: Ask what roles you have and what they allow

## Security Best Practices

<Note>
  **Access control tips:**

  * Assign minimum necessary permissions
  * Review user roles quarterly
  * Remove unnecessary roles promptly
  * Don't share accounts (each person gets their own)
  * Use Administrator role sparingly (only 1-2 people)
  * Document why custom roles were created and what they're for
</Note>

## Need Help?

<CardGroup cols={2}>
  <Card title="Managing Users" icon="users-gear" href="/tontines/organization-users/managing-users">
    How to assign and remove roles
  </Card>

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