Skip to main content
Agatabo protects your organization’s financial data through a flexible, role-based access control (RBAC) system. Every action a user can take — recording a deposit, approving a loan, viewing a report, closing a period — requires a specific permission. Those permissions are bundled into roles, and roles are assigned to users. Because permissions are cumulative across all of a user’s roles, you can compose granular access profiles that match exactly what each person needs to do their job — nothing more, nothing less.

​
Core Concepts

​
Permission Format

Every permission in Agatabo follows the pattern resource:action. The resource identifies what is being acted upon; the action describes what the user can do with it.
ExampleWhat It Grants
savings:writeRecord deposits and withdrawals
loans:readView loan details and installment schedules
expenses:writeRecord and categorize expenses
audit_logs:readView the organization’s audit trail
settings:writeModify organization settings

​
SELF vs. ANY Scopes

Every permission grant carries a scope that controls the breadth of data the user can access:
ScopeAccess LevelExample
SELFOnly the user’s own recordsA member reading their own savings balance
ANYAll records across the entire organizationA treasurer reading every member’s savings balance
Scope examples in practice:
  • savings:read with SELF → you can view your own savings history only
  • savings:read with ANY → you can view every member’s savings history
  • loans:write with SELF → you can apply for a loan on your own behalf only
  • loans:write with ANY → you can create a loan for any member
Scope precedence: When a user holds the same permission through two different roles — one granting SELF and one granting ANY — the ANY scope always takes precedence. A user with savings:read SELF from a Member role and savings:read ANY from a Treasurer role effectively has savings:read ANY.
The audit_logs:read permission requires the ANY scope specifically. Even if a user holds this permission, Agatabo will reject the request unless the scope is ANY.

​
How Agatabo Checks Permissions

Every time you perform an action in Agatabo, the system runs through these steps:
  1. Authenticates your token — a valid Bearer token and x-organization-id header are required.
  2. Resolves your organization membership — confirms you are a member of the organization in the header.
  3. Builds your effective grant set — collects all permission grants from every role you hold and merges them (ANY scope wins over SELF for duplicate keys).
  4. Checks for the required permission — if it’s absent, you receive a 403 Insufficient permissions error.
  5. Validates scope — if the endpoint requires ANY scope and you only hold SELF, you receive 403 Insufficient permission scope.
  6. Validates SELF restriction — if you hold only SELF scope and are attempting to access another member’s data, you receive 403 Permission scope denied.
System administrators bypass all permission checks automatically. All other users — including organization admins — must hold the explicit grants described here.

​
View Your Own Permissions

To see exactly which permissions you currently hold and at what scope, call: 
GET /me/permissions
Headers:
  Authorization: Bearer {accessToken}
  x-organization-id: {organizationId}
Response: 
{
  "organizationUserId": "orguser-123",
  "roleKeys": ["treasurer", "member"],
  "grants": [
    { "permissionKey": "savings:read",    "scope": "ANY" },
    { "permissionKey": "savings:write",   "scope": "ANY" },
    { "permissionKey": "expenses:write",  "scope": "ANY" },
    { "permissionKey": "loans:read",      "scope": "SELF" }
  ]
}
This endpoint reflects your effective grants — after scope precedence has been applied across all your roles. Use it as your first debugging step whenever you receive a permission error.

​
Complete Permission List

CategoryPermission KeyDescription
Organization Usersorganization_users:readView the member list and individual member details
organization_users:writeAdd, edit, and remove organization members
organization_user_roles:readView role definitions and their grants
organization_user_roles:writeCreate, edit, and delete role definitions
organization_user_roles:assignAssign and unassign roles to users
Savingssavings:readView deposit and withdrawal history
savings:writeRecord deposits and withdrawals
Loansloans:readView loan details and installment schedules
loans:writeCreate new loans and record payments
loans:modifyModify existing loan terms
loans:approveApprove loan applications
Bank Accountsbank_accounts:readView bank account list and current balances
bank_accounts:writeCreate, update, and delete bank accounts
Expensesexpenses:readView the expense history
expenses:writeRecord and categorize expenses
Assetsassets:readView the fixed asset register
assets:writeAdd, modify, and dispose of assets
Reservesreserves:readView reserve balances
reserves:writeAllocate funds to reserves and release them
Dividendsdividends:readView dividend pools and distribution history
dividends:writeCreate dividend pools and distribute dividends
General Ledgerledger:readView ledger accounts, journal entries, and the trial balance
ledger:writePost manual journal entries
Reportsreports:readAccess financial reports (balance sheet, profit & loss, etc.)
Settingssettings:readView organization settings
settings:writeModify organization settings
Period Closingperiods:closeClose accounting periods and undo period closes
Audit Logsaudit_logs:readView the audit trail (requires ANY scope)

​
Example Role Configurations

These examples reflect typical setups. Your organization defines its own role names and permission sets — the configurations below are starting points, not fixed templates.

​
Administrator

Administrators oversee the entire organization and need unrestricted access to every function.
All of the following with ANY scope:
  • organization_users:write — manage all members
  • organization_user_roles:assign — assign and revoke roles
  • savings:write — record deposits and withdrawals
  • loans:write, loans:modify, loans:approve — full loan management
  • expenses:write — record and categorize expenses
  • assets:write — manage the fixed asset register
  • reserves:write — allocate and release reserves
  • dividends:write — distribute dividends
  • bank_accounts:write — manage bank accounts
  • ledger:write — post manual journal entries
  • settings:write — change organization settings
  • periods:close — close accounting periods
  • audit_logs:read — view the full audit trail
  • reports:read — access all financial reports

​
Treasurer

The Treasurer handles daily cash flow — deposits, withdrawals, expenses, and financial reporting — without touching loans, settings, or role management.
All of the following with ANY scope:
  • organization_users:read — view the member list
  • savings:write — record deposits and withdrawals
  • expenses:write — record and categorize expenses
  • bank_accounts:read — view bank account balances
  • ledger:read — view ledger accounts and journal entries
  • reports:read — view financial reports

​
Loan Officer

The Loan Officer manages the full loan lifecycle — creating, modifying, and approving loans — but has no write access to savings, settings, or role management.
All of the following with ANY scope:
  • organization_users:read — view members to verify eligibility
  • loans:write — create loans and record payments
  • loans:modify — adjust loan terms when needed
  • loans:approve — approve pending loan applications
  • savings:read — view member savings to assess eligibility
  • reports:read — view reports

​
Member

The standard Member role lets individuals view their own financial information without exposing any other member’s data.
All of the following with SELF scope:
  • organization_users:read — view own profile information
  • savings:read — view own savings balance and history
  • loans:read — view own loan details and payment schedule
  • ledger:read — view own ledger account statement
When you assign the member role to a user, Agatabo automatically creates a savings ledger account for that person. No additional setup is required.

​
Principle of Least Privilege

The most important security guideline for managing Agatabo permissions is least privilege: grant each user only the permissions they genuinely need to fulfill their responsibilities, and nothing beyond that. In practice, this means:
  • Start minimal, add as needed. Begin with a read-only role and expand access when a specific need arises.
  • Default to SELF scope for member-facing roles. Members rarely need to see each other’s financial data.
  • Reserve ANY scope for operational staff — treasurers, loan officers, and administrators whose work requires visibility across all accounts.
  • Limit who can assign roles. The organization_user_roles:assign permission is especially sensitive — a user with this permission can grant themselves or others any level of access. Restrict it tightly.
  • Separate duties. Don’t combine the Treasurer and Loan Officer functions in a single role unless your organization is too small to avoid it. Separation reduces both error and fraud risk.
  • Review role assignments regularly. Revoke roles promptly when a person’s responsibilities change or they leave the organization.
  • Use isProtected: true for critical roles to prevent accidental deletion.

​
Troubleshooting

This error means your account does not hold the required permission at all. Call GET /me/permissions to see your current grants, identify the missing permission, and ask your administrator to assign a role that includes it. After the role is assigned, log out and back in to refresh your access token.
A simple rule: use SELF for any permission a regular member needs to manage their own account (view my savings, view my loans). Use ANY for staff whose job requires visibility across all member accounts (record a deposit for any member, view all loans for reporting). When in doubt, start with SELF and upgrade to ANY only when a specific workflow requires it. Remember: if a user holds both scopes for the same permission through different roles, ANY always wins.
Call GET /me/permissions with your Bearer token and x-organization-id header. The response lists every permission key and its effective scope. This is the ground truth — it reflects the merged result of all your assigned roles with scope precedence already applied.
The admin role cannot be assigned or unassigned through the standard role-assignment endpoints. Use the dedicated set-admin endpoint to restore administrator access. If no one in the organization retains admin access, contact your system administrator for emergency restoration.

Settings Overview

Return to the top-level settings guide to see how permissions fit alongside other configuration areas.

Audit Trail

Review the audit log to track every role assignment, permission change, and administrative action.