# OMNL Fineract API Configuration

**Last updated:** 2026-02-10  
**Tenancy:** [https://omnl.hybxfinance.io/](https://omnl.hybxfinance.io/)

## Overview

The OMNL tenancy runs Apache Fineract (Mifos) at `https://omnl.hybxfinance.io/`. API access uses **HTTP Basic** and a required tenant header. This deployment does **not** use separate HTTP request signing (no extra signature headers on each call).

| Item | Value |
|------|--------|
| Base URL | `https://omnl.hybxfinance.io/fineract-provider/api/v1` |
| Swagger UI | [swagger-ui/index.html](https://omnl.hybxfinance.io/fineract-provider/swagger-ui/index.html) |
| Tenant ID | `omnl` |
| Auth | **Basic** — either `Authorization: Basic <base64(username:password)>` or the same value from `POST …/authentication` as **`base64EncodedAuthenticationKey`** |

## Credentials

- **Username:** `app.omnl`
- **Password:** Store only in `.env` or a secrets manager; do not commit.

Use the workspace root `.env` or the `omnl-fineract/` directory env (see below).

## Environment Variables

In root `.env` or `omnl-fineract/.env`:

```bash
OMNL_FINERACT_BASE_URL=https://omnl.hybxfinance.io/fineract-provider/api/v1
OMNL_FINERACT_TENANT=omnl
OMNL_FINERACT_USER=app.omnl
OMNL_FINERACT_PASSWORD=<your-password>
```

Root `.env.example` includes commented placeholders for these variables.

## Submodule Directory: `omnl-fineract/`

The **omnl-fineract** directory at the repo root contains:

- **.env.example** / **.env.template** — Template env files (no real password).
- **.gitignore** — Ignores `.env` and logs.
- **README.md** — Quick start and API reference.
- **SETUP.md** — Step-by-step setup and verification.

To use it:

1. `cd omnl-fineract && cp .env.example .env`
2. Edit `.env` and set `OMNL_FINERACT_PASSWORD`.
3. Source `.env` and run scripts or curl as in `omnl-fineract/README.md`.

This directory can later be moved to its own repository and added as a git submodule.

## Verifying the API

```bash
# With env loaded (e.g. source .env)
curl -s -u "${OMNL_FINERACT_USER}:${OMNL_FINERACT_PASSWORD}" \
  -H "Fineract-Platform-TenantId: ${OMNL_FINERACT_TENANT}" \
  "${OMNL_FINERACT_BASE_URL}/offices"
```

Expected: HTTP 200 and a JSON array of offices.

Optional login step (returns the same Basic credential Fineract expects):

```bash
curl -s -X POST "${OMNL_FINERACT_BASE_URL}/authentication" \
  -H "Fineract-Platform-TenantId: ${OMNL_FINERACT_TENANT}" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"${OMNL_FINERACT_USER}\",\"password\":\"${OMNL_FINERACT_PASSWORD}\"}" \
| jq -r '.base64EncodedAuthenticationKey'
# Then: Authorization: Basic <that value>
```

Helper: `scripts/omnl/omnl-fineract-authentication-login.sh`.

## Related

- [mifos-omnl-central-bank/MIGRATION_AND_LEDGER_ALLOCATION_MEMORANDUM.md](./mifos-omnl-central-bank/MIGRATION_AND_LEDGER_ALLOCATION_MEMORANDUM.md) — Migration & ledger allocation (opening balance, internal distribution, client registry).
- [mifos-omnl-central-bank/LEDGER_ALLOCATION_GL_MAPPING.md](./mifos-omnl-central-bank/LEDGER_ALLOCATION_GL_MAPPING.md) — GL mapping and journal entry implementation for the memo.
- [MIFOS_NPMPLUS_TUNNEL.md](./MIFOS_NPMPLUS_TUNNEL.md) — Tunnel setup for Mifos/Fineract.
- [PHOENIX_DEPLOY_API_GITEA_INTEGRATION.md](./PHOENIX_DEPLOY_API_GITEA_INTEGRATION.md) — Phoenix Deploy API and Gitea.
- Root [.env.example](../../.env.example) — OMNL placeholders in workspace env.