Building a financial API gateway with Apache APISIX

An API gateway becomes valuable when it creates a deliberate boundary, not when it merely forwards traffic. We built the Ireti Financial API gateway to publish a small, stable financial contract while keeping identity, authorization, financial data, and infrastructure ownership in the systems designed to manage them.

The architecture at a glance

The request path separates edge enforcement from platform authorization and financial-domain enforcement:

External application
        |
        | HTTPS and OAuth bearer token
        v
Ireti-managed API hostname
        |
        v
Apache APISIX
  - host, method, and path matching
  - rate and payload limits
  - correlation identifiers
  - response projection
        |
        | fixed private upstream
        v
Private financial authorization adapter
  - current Ireti permission decision
  - workspace and resource binding
  - financial restrictions
  - private backend credential mediation
        |
        v
Tenant-specific Apache Fineract
        |
        v
Dedicated financial data and storage

External clients cannot reach Fineract directly. APISIX is the only external ingress for the reviewed Financial API, and its upstream is fixed during provisioning rather than selected from request data.

A facade, not a transparent proxy

Publishing the complete native Fineract surface would couple consumers to backend paths, payloads, and upgrade behavior. Instead, the first version of the Ireti Financial API exposes six read-only operations:

• list and retrieve offices;
• list and retrieve clients; and
• list and retrieve savings accounts.

Every operation has a stable identifier, one reviewed permission, an exact private backend mapping, a bounded query-parameter set, and a closed response schema. Unknown routes, unlisted methods, tenant selectors, command parameters, and unexpected query keys fail closed before the financial backend is contacted.

The OpenAPI document is the editable contract source. A deterministic build generates both a reviewable JSON bundle and the APISIX route projection. Validation rejects drift, route expansion, changed upstream mappings, or missing permission metadata.

APISIX enforces, but does not authorize

We deliberately did not make APISIX the source of authorization truth.

• The identity system authenticates people and service principals and issues tokens.
• Ireti Platform owns organizations, workspaces, application activation, consent, and permission grants.
• The private financial adapter asks for the current Platform decision and enforces the fixed resource binding.
• Fineract remains authoritative for financial records and financial-domain behavior.
• APISIX applies the reviewed edge contract and protective policies.

This distinction enables same-token revocation. If an administrator removes a permission, the adapter denies the next request even when the caller reuses a token issued before revocation. A valid token proves identity; it does not freeze authorization state for the token's lifetime.

Design rule

Gateway configuration is an operational projection of approved Platform state. A route label, hostname, or APISIX record cannot grant application or workspace access.

Tenant isolation starts with placement

The initial financial model assigns each customer a dedicated Fineract runtime, databases, storage, credentials, and immutable Ireti resource binding. A request cannot select another backend using a header, query parameter, path component, or token claim.

The gateway supports two placement profiles with the same contract:

• Shared placement: one Ireti-managed APISIX runtime holds several isolated bindings.
• Dedicated placement: one APISIX runtime serves one customer or environment requiring stronger infrastructure isolation.

In both profiles, DNS, TLS server name, and the validated HTTP host select a provisioned binding. Identity and current authorization must then agree with that binding. Knowing a hostname grants nothing.

We tested shared placement with synthetic backends on separate internal networks. Each host reached only its assigned backend, caller-supplied tenant overrides had no effect, unknown hosts returned no route, and cleanup restored the dedicated topology.

Stable responses at the edge

A facade is not stable if it advertises a closed schema while returning every field supplied by the backend.

Successful responses therefore pass through operation-specific APISIX transformations that:

• retain only fields declared by the public contract;
• filter nested option and currency structures;
• normalize backend date arrays to ISO dates; and
• normalize savings balances across differing list and detail representations.

Non-success responses pass through unchanged so the private adapter retains responsibility for authorization and domain failures. Response transformation is also bounded by a fixed buffer limit.

This projection lets Fineract evolve without silently broadening the external data surface.

Protective policies without commercial metering

The gateway applies a small set of operational controls:

• a per-binding and source request limit;
• a bounded request-body size;
• generated or preserved correlation identifiers;
• route-level internal metrics; and
• secret-safe telemetry that excludes tokens and financial payloads.

These counters protect the service. They are not subscriptions, API products, billing records, or commercial usage meters. The APISIX deployment is private Ireti security infrastructure, not a customer-managed gateway product.

The Admin API, configuration store, credentials, private metrics, Fineract runtime, and financial databases remain inaccessible from client networks.

Application and delegated access

Application access uses a confidential service principal and Client Credentials. The caller's application permission is checked against current Platform state before the adapter obtains private Fineract authority.

Delegated access retains two separate identities:

1. a secretless browser client authenticates a human using Authorization Code with PKCE; and
2. a confidential backend uses its own application permission to call the Financial API.

The delegated operation requires the active human, calling client, current consent, exact workspace, permitted account, and backend application grant. A browser token never becomes direct Fineract authority, and revoking delegated consent denies an already-issued human token without weakening backend application authorization.

Reconciliation and rollback

Routes are generated and reconciled rather than edited manually. The reconciliation process is idempotent: applying the same approved projection converges on one private upstream and the expected routes.

Removing the protected binding is the bounded rollback. It removes the public facade routes without changing the financial application, identity configuration, Platform grants, Fineract records, or customer data.

The final implementation was accepted through incremental proofs:

1. deploy an empty APISIX foundation;
2. define and validate the API contract;
3. generate deterministic APISIX resources;
4. prove private network reachability;
5. prove authorization, selective revocation, and cleanup;
6. add protective policies and response conformance;
7. reconcile persistent routes;
8. prove shared-placement isolation; and
9. route delegated access through the same facade.

Small slices made each security property measurable and kept rollback available throughout the migration.

What this boundary gives us

The resulting gateway is intentionally narrow. It gives external applications a versioned Ireti contract, gives operators deterministic configuration and rollback, and keeps financial data behind a private authorization chain.

Just as importantly, it does not absorb responsibilities that belong elsewhere. Identity remains identity, Platform authorization remains current and authoritative, financial rules remain close to the financial system, and APISIX remains a focused enforcement layer.

Share this article on LinkedIn