Why it matters
A modern bank serves customers through its own apps, partners’ apps, branches and payment rails at the same time. If each of these connects to the core in its own way, every change becomes a project and every new partner a risk. API-first design says: decide the interface first, publish it, version it and put controls in front of it. Channels and partners then build against a stable contract rather than against the core’s internals.
The model explained
Layers of an API-first bank
Text description
Channels and partners call the API gateway. The gateway authenticates and limits traffic, then passes requests to orchestration services, which call core adapters that talk to the core banking system.
- Channels, partners and fintechs to API gateway: identity, mutual TLS, rate limits, logging
- API gateway: identity, mutual TLS, rate limits, logging to Orchestration services
- Orchestration services to Core adapters
- Core adapters to Core banking system
Channels are the callers: the bank’s apps, partner apps, internal tools. The gateway is the front door. It checks who is calling, enforces quotas, rejects malformed requests and records every call. Orchestration services combine steps into a business action, such as “open an account” or “make a payment”, calling several systems in the right order. Core adapters translate between clean APIApplication programming interface. A defined way for one system to request data or actions from another. models and the core’s own interfaces, so the core can change, or be replaced, without breaking every caller.
What the gateway is responsible for
- Identity: every call carries credentials; partners are identified by certificates or tokens.
- Mutual TLS: for machine-to-machine traffic, both sides present certificates, so each proves who it is.
- Rate limits and quotas: a misbehaving partner cannot exhaust capacity meant for everyone.
- Validation: requests that do not match the published schema are rejected before they reach anything valuable.
- Observability: every request is logged and traced, which is how incidents are investigated later.
Designing good bank APIs
Good bank APIs share a few habits. They name business resources, such as accounts, payments and mandates, rather than exposing internal tables. Every request that moves money accepts an idempotency key, so a retried call cannot pay twice. Lists are paged, so one call cannot pull a million transactions. Errors use stable, documented codes that tell the caller whether to retry, correct the request or give up. Timestamps carry time zones, and amounts carry currencies. These details sound small, but they decide whether partners can build reliable products on top.
Versioning, sandboxes and certification
Published APIs change slowly and carefully. A new version runs alongside the old one for a notice period, and callers move across on their own schedule. Partners build first against a sandbox with test data, then pass a certification step before they get production access. For shared public infrastructure, the operator usually publishes the specification and runs the certification.
Onboarding a partner is as much a governance process as a technical one. Before production access, the bank checks who the partner is, what data the use case genuinely needs and how the partner will protect it. Access is then scoped to exactly that use case, reviewed periodically and withdrawn when the relationship ends. A register of every partner, credential and permitted operation makes those reviews possible.
How it plays out in Indian banking
India’s Account Aggregator (AAAccount Aggregator. An RBI-licensed firm that moves a customer's financial data between institutions only with the customer's consent. It does not store the data.) framework is API-first thinking applied to data sharing across the whole financial system. RBI issued its Master Direction for Account Aggregators on 2 September 2016; an Account Aggregator must be a non-bank financial company registered with RBI.1Reserve Bank of India. Master Direction - Non-Banking Financial Company - Account Aggregator (Reserve Bank) Directions, 2016 (updated 6 September 2024). As of 6 September 2024. No financial information is retrieved, shared or transferred through an Account Aggregator without the customer's explicit consent, and joining is voluntary.2Department of Financial Services, Ministry of Finance. Account Aggregator Framework. As of 29 September 2026. Customer data passing through an Account Aggregator is not visible to, and does not reside with, the aggregator.3Securities and Exchange Board of India. Consultation paper on Financial Information Users in the securities markets under the Account Aggregator framework. As of 1 August 2023. Everyone builds to one published specification: Financial information users in the Account Aggregator framework adopt technical specifications published by ReBIT.3Securities and Exchange Board of India. Consultation paper on Financial Information Users in the securities markets under the Account Aggregator framework. As of 1 August 2023.
A consented data request through an Account Aggregator
Text description
- Customer to Lender (FIU): Apply for a loan
- Lender (FIU) to Account Aggregator: Ask for consent
- Account Aggregator to Customer: Show the request
- Customer to Account Aggregator: Approve
- Account Aggregator to Bank (FIP): Fetch, with consent
- Bank (FIP) to Account Aggregator: Encrypted data (response)
- Account Aggregator to Lender (FIU): Pass it on (response)
The same pattern extends to lending. The Reserve Bank Innovation Hub describes itself as a wholly owned subsidiary of RBI; its work includes the Unified Lending Interface and MuleHunter.ai.4Reserve Bank Innovation Hub. Reserve Bank Innovation Hub. As of 29 September 2026.
Trade-offs
| Choice | You gain | You give up |
|---|---|---|
| One gateway for all traffic | Consistent security and visibility | A critical component that must scale and stay available |
| Thin core adapters | The core can be replaced behind a stable interface | Another layer to build and run |
| Long version overlaps | Partners are not forced to change at once | More versions to support and test |
| Shared public specifications | One integration works with every participant | Less freedom to add bank-specific features |
Failure modes
- The gateway becomes the bottleneck because it was sized for normal traffic, not for a salary day or a festival sale.
- Orchestration leaks into the gateway, turning it into a hard-to-test tangle of business rules.
- Breaking changes reach callers because a version was changed in place instead of added alongside.
- Over-broad access, where a partner token can do more than its use case needs.
When to use it, and when to avoid it
Use API-first design wherever more than one caller needs the same capability, and certainly wherever partners are involved. Avoid publishing an API for something only one internal system will ever use; a direct, well-tested link may be simpler. Avoid exposing the core’s own data model as the public API, because it ties every caller to the core forever.
Questions for a design review
- Is this interface designed for its callers, or does it mirror the core’s own data model?
- How are partners identified, and what exactly can each partner’s credentials do?
- What are the rate limits for a salary day or a festival sale, not just a normal day?
- How will a breaking change be introduced without forcing every caller to move at once?
- Can every request be traced from the gateway to the core and back?