User Management and Role-Based Access Control

Apache Fineract has a built-in user management and access control system. Every person who interacts with the system - whether through the web interface or the API - has a user account. That account belongs to an office, is assigned one or more roles, and those roles determine exactly which actions the user can take and which data they can see.

This system makes it possible to run a multi-branch institution on a single Fineract instance while ensuring that a loan officer in one branch cannot access another branch's client files, and that a teller cannot approve loans.

Users

A user account consists of:

• A username and password used to authenticate
• An office assignment - the office the user belongs to
• A staff record link (optional) - connecting the user to a staff member in the system, which is required for loan officers who are assigned to client accounts
• One or more roles - which determine permissions
• An email address for password resets and notifications

Users are per-tenant. An account in one Fineract tenant has no access to any other tenant.

Roles and Permissions

A role is a named collection of permissions. Fineract ships with several default roles, and custom roles can be created to match your institution's exact organisational structure.

Default Roles

Role	Typical use
Super user	Full access to all functions and all data. Reserved for system administrators.
Admin	Administrative access without some destructive operations.
Loan Officer	Create and manage loan applications, disburse and collect repayments. Typically scoped to their own assigned clients.
Teller / Cashier	Process over-the-counter cash transactions.
Read-Only	View portfolio data without making changes. Used for auditors, board members, and reporting users.

These default roles can be used as-is, modified, or supplemented with custom roles.

Permissions

Permissions are granular: each one represents a specific action on a specific resource. Examples include READ_LOAN, APPROVE_LOAN, DISBURSE_LOAN, CREATE_CLIENT, DELETE_SAVINGSACCOUNT, and several hundred more.

A role is simply a list of these permissions. Assigning a role to a user grants them all of the permissions in that role.

A user with multiple roles has the union of all permissions across those roles.

Creating a Custom Role

To create a role that allows viewing client data and loan accounts but not modifying anything, you would create a role and assign only READ_* permissions. To create an auditor role with access to accounting reports but not client data, you assign only the relevant accounting permissions.

Role and permission management is available through the web UI under Administration, or via the roles API endpoint.

Office Scoping

Fineract enforces data access by office. A user assigned to "Nairobi Branch" can only see clients, loans, and savings accounts that belong to that branch or any branch below it in the hierarchy.

This means:

• A branch manager at "Nairobi Branch" sees all client data for that branch
• A regional manager at the "East Africa Region" office (which is the parent of Nairobi Branch) sees data for all branches under that region
• A head office administrator sees data across all offices

The office hierarchy controls what data is visible - permissions control what actions can be taken on that data. Both must be satisfied for an action to succeed.

A user at a child office cannot access data from a sibling office, even if they have the relevant permissions. Data isolation is enforced at the query level, not just the UI level.

Staff Assignment

Users who work as loan officers must be linked to a staff record. The staff record is what appears on loan accounts, client records, and assignment reports. When a loan officer logs in and views their dashboard, they see the clients and loans assigned to their staff record - not just to their user account.

Creating a user with a staff link:

1. Create a staff record first (name, office, is-loan-officer flag)
2. Create the user and pass the staffId field pointing to that staff record

A user can exist without a staff link (for administrative users, auditors, etc.). A staff record can exist without a linked user (for former employees whose records remain on loans).

Password Policy

Fineract enforces a minimum password length and requires that passwords are not the same as the username. On a new Finecko instance, the default admin password is password and must be changed immediately.

Users can be sent a password reset email at creation time (set sendPasswordToEmail: true). Password resets can also be triggered by an administrator at any time.

API Authentication

The Fineract API uses HTTP Basic Authentication. Every API request must include an Authorization header with the user's credentials encoded in Base64:

Authorization: Basic <base64(username:password)>

All API actions are subject to the same role and office scoping rules as the web UI. An API client using a loan officer's credentials can only access that loan officer's data and perform actions within their permissions.

There is no token expiry or session timeout on Basic Auth - credentials are validated on every request. For programmatic integrations, create a dedicated service user with only the permissions your integration requires, rather than using an administrator account.

Practical Access Control Examples

Multi-branch institution with branch-level isolation:

• Create one office per branch under the Head Office
• Create one user per branch staff member, assigned to their branch office
• Assign the Loan Officer role to loan officers, the Teller role to tellers
• Branch staff see only their branch's clients and accounts

Auditor with read-only access to all branches:

• Create a user at the Head Office level (or any parent office)
• Assign the Read-Only role
• The user can view all data across the office hierarchy but cannot make any changes

External reporting integration:

• Create a dedicated user account at the Head Office
• Create a custom role with only READ_REPORT and RUN_REPORT permissions
• Use those credentials for the integration - no risk of accidental data modification

Multi-tenant SaaS with per-tenant super users:

• Each tenant has its own user database - there is no cross-tenant user
• Create a super user per tenant for administration
• The Finecko Hub handles tenant provisioning; each new tenant starts with the default mifos admin which your team configures before handing over to the customer

For step-by-step API instructions on creating users and roles, see the Getting Started guide and the interactive Swagger UI at your instance URL.