Skip to main content

​
Introduction

The Nigerian Open Banking API uses OAuth2-based authentication methods to enable consent management and adapts it to suit different types of applications and data access levels.
Please note that App developers MUST NOT request for customer password, pin or any other senstive data. It is not allowed.
Depending on your app’s capabilities and the nature of the API you’re calling, choose the appropriate flow:
Designed for devices or interfaces with limited input or no browser, such as USSD apps, SMS flows etc.
  • For dumb terminal authentication
  • Use when your application is running on dumb channels e.g. USSD or SMS based application
  • Also if target customer does not have smart devices, you can use this.
  • Example includes customers with no sophisticated phones or laptop, desktop computer, ipad etc but have access to USSD or SMS
  • It allows customers to authenticate and give consent over dumb channels
  • Note that developer app can start transaction processing (payment etc) via smart channel and complete authentication via dumb channel e.g. transfer initiated on web but authentication done via USSD.
  • Similarly developer app can start transaction processing (payment etc) via dumb channel and authentication completed via smart channel e.g. payment initiated via USSD and authenticated done via device authentication URL via a web browser.
  • Sparkle will determine authentication channels available to Customer
  • Authentication channel to be used will be determined when call to device authorization is made
  • Sparkle can also decide to give multiple authentication channel options to customer
User code must always be displayed to the customer.

​
🔁 Device Authentication Flow

Use this for confidential clients such as web and mobile apps with secure backends.
  • Involves redirecting users to authenticate.
  • Requires client secret.
  • Best suited for apps that can securely store secrets.
  • Typically used for APIs that require customer consent, such as accessing account data or initiating payments.

​
🔁 Authorization Code Flow

Recommended for Single Page Applications (SPAs) or other public clients that cannot securely store a client secret.
  • Uses a temporary code verifier and challenge instead of client secret.
  • Enhances security in public clients.
  • Ideal for: browser-based apps and mobile apps without backends.
  • Also used for APIs requiring customer consent.

​
🔁 PKCE Authorization Flow

​
4. Client Credentials Flow

Used for system-to-system authentication where no customer consent is required.
  • Your backend sends client_id and client_secret directly to obtain a token
  • No redirect, user interaction, or consent needed
  • Ideal for:
    • Openign new accounts
    • Getting Biller Categories
    • Getting Billers
    • All Meta APIs e.g. discover APIs, Get Bank branches
    • Other non-sensitive, public or service-level APIs

​
🔁 Client Credentials Flow

​
5. Basic Authentication

This method is used for direct server-to-server communication, usually for legacy or internal APIs that do not require OAuth flows.
  • Involves encoding client_id:client_secret in Base64 and sending it in the Authorization header.

​
🧠 Summary Table

FlowUse CaseRequires Customer Consent?Client Secret Required?
Device CodeUSSD, SMS, ATMs, smart terminals✅ Yes✅ Yes
Authorization CodeWeb/mobile apps with backend✅ Yes✅ Yes
PKCESPAs, public mobile apps✅ Yes❌ No
Client CredentialsBackend-to-backend APIs (e.g., billers)❌ No✅ Yes
Basic AuthenticationBackend-to-backend APIs (e.g., billers)❌ No✅ Yes

​
Available Scopes

ScopeDescriptionAccess Level
customers.readonlyView customersCustomer data access
customers.updateUpdate a customerCustomer management
accounts.createCreate an accountAccount creation
accounts.list.readonlyView accountsAccount data access
accounts.balance.readonlyView account balanceBalance information
accounts.updateUpdate an accountAccount management
accounts.transactions.readonlyView transactionsTransaction data access
accounts.holds.readonlyView holdsAccount hold information
accounts.holds.createPut a hold on funds in an accountAccount hold management
accounts.holds.updateRelease a hold on funds in an accountAccount hold management
transfers.transactions.enquiryValidate an account numberTransfer verification
transfers.transactions.createMake a transferTransfer initiation
transfers.transactions.queryQuery transfer transactionsTransfer status tracking
bills.categories.listView bill categoriesBill payment categories
bills.billers.listView billersBill payment providers
bills.bill.validateValidate a billBill payment validation
bills.transactions.createCreate a bill payment transactionBill payment initiation
disputes.categories.listView dispute categoriesDispute management
disputes.report.createCreate a dispute reportDispute reporting
disputes.report.readonlyView disputesDispute information
direct-debits.createCreate a direct debitDirect debit setup
direct-debits.updateUpdate a direct debitDirect debit management
direct-debits.listView and manage direct debitsDirect debit overview
direct-debits.readonlyView existing direct debitsDirect debit information
direct-debits.transaction.createCreate a direct debit transactionDirect debit processing
cards.listView cardsCard management
cards.updateUpdate a cardCard modification
cards.createCreate a cardCard creation
loans.listView and manage loansLoan information
savings.listView and manage savingsSavings account management
savings.transactions.listView and manage savings transactionsSavings transaction data

​
🔑 Accessing the Open API

The Nigerian Open Banking APIs support two main authentication schemes depending on the type of API being accessed:

​
1. Bearer-Based Access Token (OAuth2)

Most Open API endpoints that involve customer data, transactions, or secure operations require an OAuth2 Bearer access token. These access tokens are obtained through one of the supported OAuth2 authentication flows:
  • Authorization Code Flow
  • PKCE Flow
  • Device Authorization Flow
  • Client Credentials Flow
APIs to use Client Credentials Flow for:
  • Open New Account
  • Get Billers Categories
  • Get Billers
  • Get Dispute Categories
APIs to use Authorization Code/PKCE/Device Authorization Flow for:
  • All APIs apart from the Meta APIs and the APIs listed above
Your application must include the access token in the Authorization header: 
authorization: Bearer <access_token> <!-- OAuth 2.0 access token -->
signature: <signature> <!--  Request signature for security.] -->
idempotency_key: <idempotency_key>  <!--  Unique identifier for request deduplication -->

​
Basic API Authentication

Some Open API endpoints that provide non-sensitive, meta, or informational data can be accessed using Basic Authentication. This method uses your app’s client credentials encoded in Base64 Your application must include the access token in the Authorization header: 
authorization: Basic <base64(client_id:client_secret)> 
signature: <signature> <!--  Request signature for security -->
idempotency_key: <idempotency_key>  <!--  Unique identifier for request deduplication -->
APIs to use Basic API Authentication for:
  • Get Client Credentisals (Requires username and password)
  • All Meta APIs
Note that the Get Client Credentisals API requires Basic Authentication. The username/password required is the one supplied when the Register new client application API was called.
Note that the Meta APIs also requires Basic Authentication however the client id/client secret generated when the API Register new client application replaces username/password.
See technical guide here for how to calculate signature.

​
Security Best Practices

​
1. Secure Storage

  • Store client secrets server-side only
  • Use environment variables for sensitive data
  • Never expose credentials in client-side code

​
2. Token Management

  • Store access tokens securely
  • Implement automatic token refresh
  • Clear tokens on logout

​
3. PKCE Implementation

  • Always use PKCE for web applications
  • Generate cryptographically secure random values
  • Store code verifier securely during the flow

​
4. Redirect URI Validation

  • Use exact redirect URI matching
  • Avoid wildcard redirect URIs
  • Validate redirect URIs server-side

​
5. State Parameter

  • Always include a random state parameter
  • Validate state parameter on callback
  • Use cryptographically secure random values

​
Error Handling

Common OAuth errors and how to handle them:
ErrorDescriptionSolution
invalid_clientInvalid client credentialsCheck your client_id and client_secret
invalid_grantInvalid authorization codeEnsure code is used only once and not expired
invalid_redirect_uriRedirect URI mismatchVerify redirect URI matches registration
invalid_scopeInvalid scope requestedCheck scope format and permissions
access_deniedUser denied consentHandle gracefully and retry
Always implement proper error handling and provide clear feedback to users when authentication fails.

​
Testing Authentication

Use our sandbox environment to test your authentication implementation:
  1. Register your application in sandbox
  2. Test the complete OAuth flow
  3. Verify token exchange and API calls
  4. Test error scenarios and edge cases