How to build a custom front end on the Apache Fineract API
If your team has chosen Apache Fineract as the core and now needs staff or customer screens, the first thing to accept is that Fineract provides none. It is a headless application that exposes REST APIs and no user interface of its own. The project's README points to the Mifos X web application as the front end used in its Kubernetes example, but that is an example, not a requirement. Choosing the front end, deciding how users sign in, and deciding which API surface reaches which kind of user are design decisions your implementation team must make and then own for the life of the system.
Treat those three decisions as one design. Staff screens can usually sit on the internal network with a narrow set of roles, while customer apps are exposed to the internet and need a very different boundary. Confirm with the project and your own security team which endpoints are meant for back-office use and which are suitable for self-service, and do not place staff-only operations behind a public app. Plan how the Fineract-Platform-TenantId header is set for each application so that a browser cannot choose a tenant it should not reach, and decide how paging, batch calls and errors will be handled in the client code. Verify these choices against the current Apache Fineract platform documentation rather than older tutorials.
Set expectations early. The README warns that a production deployment can be complex, costly and time-consuming, and that the project does not provide a comprehensive production deployment guide. It also notes that organizations may pay a vendor for deployment and maintenance. A custom front end adds build pipelines, session handling, hosting, monitoring and upgrade work that must be scoped in writing. Ask any partner, including DeployOpen, to state who maintains the front end after go-live, how it is tested against each Fineract release, and which parts of the cost recur.
Mifos X web app or a custom front end: which to start from
This table compares three starting points for a Fineract front end: adopting the Mifos X web application for staff, building a custom staff app, and building a separate customer app on the same API. Read each row against your own product set, branding needs and upgrade tolerance. The main takeaway is that the Mifos X choice trades build effort for dependence on an upstream UI you must verify for coverage and version compatibility.
| Factor | Mifos X web app (staff) | Custom staff app | Custom customer app |
|---|---|---|---|
| What it is for | Pre-built staff interface for branch and back-office work on Fineract's REST API | Staff interface designed around your own workflows, roles and product set | Self-service interface for customers, built on the same API but a separate application |
| Who maintains the UI code | The Mifos X project community, under its own release cycle | Your team or your partner, for the life of the application | Your team or your partner, for the life of the application |
| Fit with bespoke products | Limited to what the UI exposes; confirm coverage for your product configuration | High, since screens follow your products and rules | High for customer journeys, but limited to what the API exposes to customers |
| Branding control | Low to moderate; confirm which theming and labeling options exist | Full control over layout, language and brand | Full control over layout, language and brand |
| Upgrade impact | Tied to Mifos X release compatibility with your Fineract version; confirm in project documentation before each upgrade | Your team tests UI changes on each Fineract release, including API changes | Same as custom staff app, plus customer-facing release windows |
| Security exposure | Staff-only deployment is typical; confirm how it reaches the API and tenant headers | Staff access can be restricted to internal networks and single sign-on | Must not call self-service APIs from a public app without a gateway and auth design |
| Confirm before deciding | Current feature coverage and release compatibility with your Fineract version, in the project's own documentation | Team skills, test coverage and release ownership | Customer identity model, API exposure and rate limits |
Staff apps and customer apps need different exposure models
Branch and back-office screens act for employees who open clients, post transactions, approve work and run period-end tasks. These screens need the broadest set of Fineract resources, and a single staff screen can call several areas of the API within one workflow. Each employee's identity should map to a Fineract user with its own roles and office, so every change is attributed to a person.
- Branch screens: client onboarding, loan and savings transactions and cash handling, each calling the resources that match the employee's role.
- Back-office screens: product setup, accounting, approvals and reporting, usually limited to supervisory or finance roles.
- Identity mapping: each employee signs in through your chosen method, such as OAuth2, and the app sends the tenant header with every request.
- Credential hygiene: the README's default development login must be replaced before any shared environment, and tokens should expire under your session policy.
- Attribution: shared logins hide who did what, so each action should trace back to one named employee in your logs.
Confirm against your own role matrix which endpoints each staff screen may call, and test that a teller account cannot reach supervisory operations.
Self-service screens let customers view balances and statements and submit requests. Their traffic arrives from the internet, so it should not reach the full staff API surface. A narrower service layer in front of Fineract should expose only the operations customers need, and that layer should be governed on its own release and access cycle.
- Narrow operation set: read views and a short list of customer actions, each approved in writing, instead of the full resource model.
- Separate credentials: customers authenticate through a dedicated identity flow, never with staff accounts or the default development login.
- Server-side ownership checks: the service layer confirms that a customer can only read or change their own client and account records.
- Separate governance: its own owners, review cycle, logging, rate limits and change control, kept apart from back-office release processes.
- Network placement: the layer sits in a controlled zone, and Fineract's endpoints accept traffic only from that layer and approved internal services.
Ask your architects and security team which endpoints are safe for customer exposure, and confirm the answer against your gateway design before any customer screen is scoped.
Both audiences usually call the same Fineract instance and tenant, so the boundary must be enforced by design and not by what the interface displays. Controls at the gateway, the service layer and the logs carry most of the weight. The written endpoint inventory is the reference that auditors and engineers will both use.
- Tenant handling: both audiences send the Fineract-Platform-TenantId header, and the gateway should set it from the authenticated context and strip any value supplied by the client.
- Hidden screens are not controls: removing a button from a customer app does not stop a direct call to the same endpoint.
- Endpoint inventory: a written list per audience, reviewed whenever Fineract is upgraded or a module is added.
- Paging limits: the service layer caps page sizes so one caller cannot pull large result sets through a single request.
- Audit records: every call should log the audience, the authenticated user and the tenant, so access can be reconstructed later.
Confirm with your architects and auditors how the inventory is maintained, who signs off changes to it and where the logs are retained.
How tenant headers and authentication fit into your front end
Every request your front end sends to Fineract has to identify the tenant it belongs to, and the front end or the gateway in front of it must set that identity the same way on every call. Fineract is multi-tenant: API requests carry a Fineract-Platform-TenantId header, and the server resolves that value to a tenant connection configured from a tenants database. A staff app that sends the header inconsistently can read or write the wrong institution's data, so treat the header as part of the security boundary, not as a convenience. Decide where it is set (in the browser code, in a backend-for-frontend, or in the gateway), who may change it, and how your tests prove that a session for one tenant cannot be replayed against another.
The README shows OAuth2 and HTTP basic authentication. Basic authentication is useful for development and for server-to-server calls, but a customer or staff front end should not hold reusable credentials in browser storage. Before you design the login flow, confirm which token flow your chosen Fineract version supports, how tokens are issued and refreshed, and whether the token carries tenant context. The default development login, mifos with a known password, must be changed before any real deployment, and the change should be checked in your deployment pipeline rather than left to a manual step. Ask the Fineract documentation and your own platform team to confirm the exact authentication settings for your release.
Use HTTPS only. The Fineract documentation strongly encourages it and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Plan TLS termination at the gateway or at Fineract itself, decide how certificates are issued and rotated, and confirm that the front end never calls Fineract over plain HTTP, including from internal test environments that later become production templates. The planning output for this section should be a short written contract covering the tenant header source, the login and token flow, the password change step, and the TLS configuration, reviewed by the security team before any screen is built.
Setup sequence for a custom front end on the Fineract API
This sequence takes a team from choosing a Fineract release to a tested custom front end that talks to headless Fineract through a controlled tenant, identity and gateway layer. Each step ends with a check the team can repeat before any staff or customer traffic reaches the platform.
Confirm the Fineract version and read its API documentation
Confirm which Fineract release your environment runs, then read the API documentation for that exact version rather than a generic reference. The project lists 1.15.0 as the current stable release, but your deployed version may differ, so the endpoint names, request fields and error responses you build against must come from the release you operate. Ask your platform owner to record the version in the project plan. Done when the team has a written version number and a list of the endpoint groups it will call.
Decide the front-end starting point
Choose whether to start from the Mifos X web application or build a new front end on the REST API. Fineract is headless and does not ship its own user interface, and the project points to Mifos X as a front end used in its Kubernetes example. Evaluate how far its screens, workflows and tenant handling match your staff processes and customer journeys, and list what would need rewriting. Done when the team has a signed decision that names the starting point and the parts that will be built new.
Define audiences and their endpoint sets
Split the front end into audiences, typically back-office staff, branch or field users and customers, and assign each audience only the endpoints it needs. Staff screens and self-service screens should not share one broad API surface, because self-service endpoints are designed for a different trust level. Record each endpoint group per audience and mark any that must never be reachable from a public application. Done when the team has an endpoint matrix that a reviewer can check against the planned screens.
Set up the identity provider and token flow
Configure the identity provider that issues tokens for each audience, and wire the Fineract authentication settings to accept them. The Fineract README shows OAuth2 and HTTP basic authentication, and its development login uses a default username and password that must be changed for any real deployment. Confirm the token flow for each client type and document token lifetimes and claims your identity team controls. Check that the default development credentials no longer work and that a token for one audience is refused on endpoints reserved for another.
Place a gateway or backend layer for tenant and HTTPS
Put a gateway or backend-for-frontend between browsers or mobile apps and Fineract. This layer sets the Fineract-Platform-TenantId header on every request so clients never choose a tenant themselves, enforces HTTPS, and blocks routes that belong only to internal or self-service audiences. The README describes multi-tenancy through this header, and the documentation strongly encourages HTTPS only with SSL settings such as FINERACT_SERVER_SSL_ENABLED. Check that a request without the tenant header is rejected, that a wrong tenant identifier is rejected, and that plain HTTP is refused.
Build paging and error handling
Implement list paging and a consistent error model in the front end and the gateway layer. Read the paging parameters that your Fineract version accepts for each list endpoint, then build components that request pages, show totals only where the API returns them, and avoid loading full portfolios into the browser. Map Fineract error responses to user messages and to log entries, and make retries safe for write operations by pairing them with the idempotency design your team has chosen. Done when a test list of a large client or loan set loads in pages and every error class you expect shows a clear message.
Run a test pass against a non-production tenant
Run the full set of screens and endpoint calls against a non-production tenant that holds representative test data, using the tenant header and identity settings you will use in production. Include negative tests: missing or wrong tenant header, expired tokens, a customer token used on a staff endpoint, default credentials, and a request over plain HTTP. Record results in a checklist that the security and platform owners sign. Done when every negative test is refused as designed and every positive journey completes against the non-production tenant, with the results kept for the release record.
Keeping self-service APIs out of public apps
A headless Fineract platform exposes every endpoint it serves, so the front end you build is only as safe as the boundary you draw around it. The cards below cover the controls that connect the API, the client code, the transport and the audit trail, and what to verify for each before a public app goes live.
Separate staff and customer API surfaces
Staff endpoints for teller, approval and back-office work should never be reachable from a customer app, even if the customer app holds a valid token. Plan two distinct entry points, each with its own route rules at the gateway and its own identity source. Verify with a test login from the customer app that staff operations are refused at the network or gateway layer, not only hidden in the interface.
Keep credentials out of client code
Any secret placed in a browser bundle, mobile app or static file is public the moment the app is installed. Keep client secrets and service credentials on a backend component you operate, and let the front end obtain only the session it needs. Verify by searching the built artifacts for tenant identifiers, usernames and secrets before each release.
Send tenant identifiers through a controlled path
Fineract is multi-tenant, and requests identify their tenant through a platform tenant header. Decide whether the public app sends that header directly or whether a backend sets it after checking the user's tenant membership. Verify that a user cannot change the header value to reach another tenant's data, and test this with a tampered request.
Enforce HTTPS on every hop
Credentials and account data must not travel over plain HTTP between the browser, gateway and Fineract. The project strongly encourages HTTPS only and documents SSL settings through environment variables. Verify that HTTP redirects to HTTPS, that the SSL setting is enabled in every instance that receives client traffic, and that certificates renew before expiry.
Remove default logins before go-live
The README ships a development login that must be changed for any real deployment. Confirm that the default account is disabled or its password replaced in every environment that is reachable from a network, including staging. Verify this by attempting a login with the documented defaults from outside the admin network and recording the refused result.
Enforce authorization on the server
Hiding a button in the front end does not stop a direct API call. Every permission decision for loans, savings and client records must be made by Fineract or by a gateway rule that the browser cannot bypass. Verify by calling each restricted operation directly with a low-privilege token and confirming the server refuses it, using the permission names confirmed in your Fineract version's documentation.
Record who acted through the interface
When a teller or customer acts through a custom front end, the audit record must show the authenticated user and the channel, not only a shared integration account. Confirm how Fineract records the acting user for requests that pass through your backend, and whether your backend forwards the end user's identity. Verify by performing a test transaction through each channel and checking that the audit entry names the correct person.
Paging, read traffic and the limits of a first release
List screens, search results and exports all depend on API paging, so the team should confirm how each Fineract endpoint it plans to call pages and sorts results in the exact version it will run before designing grids, filters or export jobs. Paging and sort parameters, default page sizes and total-count behavior can differ between endpoints, and a front end that assumes one pattern everywhere will produce wrong row counts or skipped records. Run the check against a running instance with production-like data volumes, and record the result as a contract the front end is built against. Confirm the same for any report or export endpoint, since large result sets may need a different approach than on-screen paging.
The Fineract documentation describes read, write and batch instance types, set through environment variables. It recommends one write instance, one batch instance and multiple read instances on database read replicas for high load. Front-end traffic is mostly reads, so the team should route list and detail calls to the read instances and send only state-changing requests to the write instance, typically through the ingress or gateway layer. Ask the platform team to confirm how routing is configured in their environment, and test that reads served from replicas can lag behind recent writes. A screen that shows a loan as unapproved seconds after approval is a usability and control issue, not only a performance one.
Liquibase database migrations run only on write instances, according to the Fineract documentation, and on Kubernetes they can run separately using the liquibase-only Spring profile. Front-end releases must therefore not assume that new fields, endpoints or schema changes are live on every node at the moment the new interface is deployed. Plan the release so the migration step completes first, and make the interface tolerate older responses during a rolling upgrade. This first release should stay within the endpoints and fields the team has verified, with any dependence on newer capabilities documented as a gate for a later release.
Limits to confirm before you commit to a front-end design
A headless Fineract back end leaves the user interface, its feature coverage and its notification path to you. The items below are the points where an assumption made during planning is most likely to fail once a front end meets a real tenant, version and identity setup.
Mifos X feature coverage for your products
Mifos X is the front end named in the Fineract README, but it is a separate application with its own release cycle. Ask whether it already exposes the loan, savings, client and accounting screens your staff need for the products you have configured, including any custom fields or product rules. Where it does not, estimate the build cost of the missing screens before you assume a stock front end will carry the workflow. Confirm this against the Mifos X version you intend to run.
Endpoint behavior and paging for your version
Fineract's REST endpoints differ in response shape, paging parameters and default page sizes across releases, and some list endpoints return full collections rather than pages. Check the paging parameters and sort behavior for each endpoint your screens will call against the exact release you will deploy, using the generated API documentation of that version. Test with a tenant holding realistic record volumes, since a list that loads quickly in a sandbox can time out in production.
Identity provider integration with OAuth2
Fineract supports OAuth2 and HTTP basic authentication, and the README's default development login must be replaced before any real use. Confirm how your chosen identity provider issues tokens to the front end, how roles and tenant membership are mapped to Fineract permissions, and how token lifetime and logout are handled. Ask whether the provider supports the flow your browser application needs, and who in your organization owns the mapping when staff roles change.
Need for business event notifications
Fineract publishes external business events, such as ClientCreated, to ActiveMQ, other JMS brokers or Apache Kafka, but this is disabled by default. Decide whether your front end needs push updates, such as a loan approval appearing on a staff dashboard, or whether polling the API is sufficient. If you do need events, confirm the broker you will run, the enabled event types and who operates the consumer, because enabling publishing adds infrastructure your team must secure and monitor.
Support status of your framework and UI library
Front-end frameworks and component libraries have their own end-of-life dates, security advisory processes and major-version upgrade paths, and these may not match the Fineract release cadence. Check the maintenance status, license and release policy of each framework and library you plan to adopt, and confirm that your build pipeline can still produce patched bundles after the version you choose stops receiving updates. Record the owner and review date for each dependency in your architecture decision record.
Questions teams ask before building a Fineract front end
Is Mifos X enough for our staff to run Fineract?
It depends on the workflows your staff run daily and how much you need to change them. Fineract is headless and provides no user interface of its own. The Fineract README points to the Mifos X web application as the front end used in its Kubernetes example, so it is a credible starting point for back-office work. Check each role against what the screens support: loan and savings servicing, client onboarding, accounting views, approvals and reporting. Gaps usually show up in branch workflows, custom fields, or screens for your own products. Ask the team to walk through a list of real tasks against a running instance before deciding to extend Mifos X or build your own.
What drives the cost of a custom Fineract front end?
The main cost driver is the number of distinct user journeys and roles, followed by how much business logic lives in the screens versus in Fineract. Each journey needs design, build, testing and access control. Staff apps with approval paths and audit views cost more than read-only dashboards. Self-service customer apps add identity proofing, consent, notifications and abuse controls. Ask any partner for a quote that lists screens or journeys, roles, integrations with identity and other systems, test scope, and handover. Costs recur for hosting, dependency updates and support, so ask which items are one-time and which are retainers.
How long does a custom Fineract front end take to build?
Duration follows scope, not the framework alone. The biggest factors are the number of journeys, how many existing Fineract endpoints must be wrapped, the identity model, and how many environments and approval gates your change process requires. Teams often underestimate testing against a tenant with realistic products and business dates. Ask for a written plan with milestones, the assumptions behind each one, and the client decisions that gate progress, such as role definitions and sign-off on the authentication design. Treat any duration without these details as unsupported.
What does the work need from our own team?
Expect to supply product owners who can decide roles and workflows, an identity team that can register clients and manage the identity provider, and platform engineers who will host the front end and the Fineract environments. Someone must own the tenant list and the test data, and someone must approve access to the self-service APIs. Compliance and operations staff should review logging, session handling and change control. Ask a partner to name these contributions in the quote so you can staff them before the build starts.
Can our internal team build the front end without outside help?
Yes, if the team has experience with the chosen front-end stack, OAuth2 or OIDC, and Fineract's REST API. The skills gap is usually not the screens but the security model: tenant headers, token handling, keeping self-service endpoints away from public clients, and secure configuration of HTTPS. The Fineract documentation strongly encourages HTTPS only, and the README warns that production deployment is complex and time-consuming. Assess your team against those specific skills and consider an outside review of the design before build starts.
Which Fineract APIs should stay out of public front ends?
Staff operations and back-office endpoints should never be exposed to public browsers or mobile apps. Put public apps behind a gateway that exposes only self-service routes, and keep staff applications on a separate network path with stronger authentication. Confirm with your Fineract version which endpoints serve self-service and which serve staff, because the split is a design decision you must document and test. Ask the partner to show the route allow list and the tests that prove blocked paths return errors.
How do front-end upgrades keep pace with Fineract releases?
Fineract publishes official releases quarterly, at the end of each quarter, and archives end-of-life releases according to the ASF release policy, as stated in the project README. Your front end therefore needs a planned upgrade cycle, a test suite against each target release, and a record of which API endpoints it depends on. Mifos X, if used, must be upgraded in step with the backend and checked for compatibility. Ask for an upgrade procedure, the regression tests that run on each target version, and who pays for upgrades under the support agreement.
How DeployOpen scopes and delivers a Fineract front end
DeployOpen plans, builds, documents and supports the front end you choose for Apache Fineract, whether you start from the Mifos X web application or write your own client against the headless API. We keep the Fineract back end inside your infrastructure and keep self-service access separate from staff access, so the design is agreed before any screens are built.
How we scope
- Engagements are fixed-scope, with the front end's users, screens and Fineract endpoints agreed in writing before work starts.
- The written scope names which tenant headers, authentication flows and paging behavior each application must handle.
- We confirm whether the Mifos X web application fits your staff workflows or whether a custom client is the better option.
How we build
- We build the staff and customer clients against your chosen Fineract release, with tenant identifiers and OAuth2 sessions configured per environment.
- Self-service customer features route through a gateway or separate API layer, so administrative Fineract endpoints are never exposed to public apps.
- We test paging, error handling and retry behavior against a running Fineract instance before any user acceptance testing begins.
How we hand over
- Handover includes source code, build instructions, environment configuration and a written map of which Fineract endpoints each screen calls.
- Documentation covers credential rotation, tenant configuration and the steps needed to repeat deployments in your environment.
- Your team receives a walkthrough of the authentication model and the list of endpoints that must stay off public networks.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, so front end changes can follow Fineract release updates.
- Before each Fineract upgrade, we can review client compatibility against the new release and the generated API definitions.
- Ask any provider to confirm how front end releases, rollbacks and security patches are scheduled within your change process.
