> ## Documentation Index
> Fetch the complete documentation index at: https://docs-sandbox.sparkle.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Consent Management

> Learn how to obtain customer consent with the Open Banking API using OAuth 2.0

## 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.

<Note> Please note that App developers `MUST NOT` request for customer password, pin or any other senstive data. It is not allowed.</Note>

Depending on your app's capabilities and the nature of the API you're calling, choose the appropriate flow:

## Consent Based Authentication

***

### 1. Obtaining Consent via Device Authorization Flow (Dumb Channels)

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

<Note>
  User code must always be displayed to the customer.
</Note>

#### 🔁 Device Authentication Flow

<Accordion title="Device Authentication Flow">
  ```mermaid theme={null}
  sequenceDiagram
      participant App Frontend
      participant App Backend
      participant OpenAPI
      participant Customer
      participant Sparkle Identity Server

      App Frontend->>App Backend: Request device token
      App Backend->>OpenAPI: Request device token
      OpenAPI-->>App Backend: Returns user_code, device_code and consent_message
      App Backend-->>App Frontend: Returns user_code and consent_message
      App Frontend->>Customer: Display consent_message and user_code

      alt Web-based
          Customer->>Browser: Visit auth URL and Enter user_code
          Sparkle Identity Server->>Customer: Prompt for username
          Customer->>Sparkle Identity Server: Enter username
          Sparkle Identity Server->>Customer: Prompt for password
          Customer->>Sparkle Identity Server: Enter password
          Sparkle Identity Server->>Customer: Request consent
          Customer->>Sparkle Identity Server: Approve scopes
      else USSD
          Customer->>Sparkle Identity Server: Dial USSD code
          Sparkle Identity Server->>Customer: Prompt for user_code
          Customer->>Sparkle Identity Server: Enter user_code
          Sparkle Identity Server->>Customer: Prompt for username
          Customer->>Sparkle Identity Server: Enter username
          Sparkle Identity Server->>Customer: Prompt for password
          Customer->>Sparkle Identity Server: Enter password
          Sparkle Identity Server->>Customer: Request consent
          Customer->>Sparkle Identity Server: Approve scopes
      end

      App Backend->>OpenAPI: Poll with device_code
      OpenAPI-->>App Backend: Return access token after successful auth

  ```
</Accordion>

***

### 2. Obtaining Consent via Authorization Code Flow (Smart Terminals)

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

<Accordion title="Authorization Code Flow">
  ```mermaid theme={null}
  sequenceDiagram
      participant User
      participant App Frontend
      participant App Backend
      participant Browser
      participant OpenAPI

      App Frontend->>Browser: Redirect user to authorization URL
      Browser->>OpenAPI: Send auth request with client_id, redirect_uri, scopes
      OpenAPI->>User: Prompt for login and consent
      User->>OpenAPI: Enter credentials and approve
      OpenAPI->>Browser: Redirect to App with authorization code
      Browser->>App Frontend: Deliver authorization code
      App Frontend->>App Backend: Deliver authorization code
      App Backend->>OpenAPI: Exchange code for access token (with client_id & client_secret)
      OpenAPI-->>App Backend: Return access token
  ```
</Accordion>

***

### 3. Obtaining Consent via PKCE Authorization Flow  (Smart Terminals)

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

<Accordion title="PKCE Authorization Flow">
  ```mermaid theme={null}
  sequenceDiagram
      participant User
      participant SPA
      participant Browser
      participant OpenAPI

      SPA->>Browser: Redirect user to authorization URL with code_challenge
      Browser->>OpenAPI: Send auth request with code_challenge
      OpenAPI->>User: Prompt for login and consent
      User->>OpenAPI: Enter credentials and approve
      OpenAPI->>Browser: Redirect to SPA with authorization code
      Browser->>SPA: Deliver authorization code
      SPA->>OpenAPI: Exchange code for token using code_verifier (no client secret)
      OpenAPI-->>SPA: Return access token
  ```
</Accordion>

***

### 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

<Accordion title="Client Credentials Flow">
  ```mermaid theme={null}
  sequenceDiagram
      participant User
      participant App Backend
      participant OpenAPI

      App Backend->>OpenAPI: Requests access token (with client_id & client_secret)
      OpenAPI-->>App Backend: Return access token
  ```
</Accordion>

***

### 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

| Flow                 | Use Case                                | Requires Customer Consent? | Client Secret Required? |
| -------------------- | --------------------------------------- | -------------------------- | ----------------------- |
| Device Code          | USSD, SMS, ATMs, smart terminals        | ✅ Yes                      | ✅ Yes                   |
| Authorization Code   | Web/mobile apps with backend            | ✅ Yes                      | ✅ Yes                   |
| PKCE                 | SPAs, public mobile apps                | ✅ Yes                      | ❌ No                    |
| Client Credentials   | Backend-to-backend APIs (e.g., billers) | ❌ No                       | ✅ Yes                   |
| Basic Authentication | Backend-to-backend APIs (e.g., billers) | ❌ No                       | ✅ Yes                   |

## Available Scopes

<Accordion title="Available Scopes">
  | Scope                              | Description                           | Access Level               |
  | ---------------------------------- | ------------------------------------- | -------------------------- |
  | `customers.readonly`               | View customers                        | Customer data access       |
  | `customers.update`                 | Update a customer                     | Customer management        |
  | `accounts.create`                  | Create an account                     | Account creation           |
  | `accounts.list.readonly`           | View accounts                         | Account data access        |
  | `accounts.balance.readonly`        | View account balance                  | Balance information        |
  | `accounts.update`                  | Update an account                     | Account management         |
  | `accounts.transactions.readonly`   | View transactions                     | Transaction data access    |
  | `accounts.holds.readonly`          | View holds                            | Account hold information   |
  | `accounts.holds.create`            | Put a hold on funds in an account     | Account hold management    |
  | `accounts.holds.update`            | Release a hold on funds in an account | Account hold management    |
  | `transfers.transactions.enquiry`   | Validate an account number            | Transfer verification      |
  | `transfers.transactions.create`    | Make a transfer                       | Transfer initiation        |
  | `transfers.transactions.query`     | Query transfer transactions           | Transfer status tracking   |
  | `bills.categories.list`            | View bill categories                  | Bill payment categories    |
  | `bills.billers.list`               | View billers                          | Bill payment providers     |
  | `bills.bill.validate`              | Validate a bill                       | Bill payment validation    |
  | `bills.transactions.create`        | Create a bill payment transaction     | Bill payment initiation    |
  | `disputes.categories.list`         | View dispute categories               | Dispute management         |
  | `disputes.report.create`           | Create a dispute report               | Dispute reporting          |
  | `disputes.report.readonly`         | View disputes                         | Dispute information        |
  | `direct-debits.create`             | Create a direct debit                 | Direct debit setup         |
  | `direct-debits.update`             | Update a direct debit                 | Direct debit management    |
  | `direct-debits.list`               | View and manage direct debits         | Direct debit overview      |
  | `direct-debits.readonly`           | View existing direct debits           | Direct debit information   |
  | `direct-debits.transaction.create` | Create a direct debit transaction     | Direct debit processing    |
  | `cards.list`                       | View cards                            | Card management            |
  | `cards.update`                     | Update a card                         | Card modification          |
  | `cards.create`                     | Create a card                         | Card creation              |
  | `loans.list`                       | View and manage loans                 | Loan information           |
  | `savings.list`                     | View and manage savings               | Savings account management |
  | `savings.transactions.list`        | View and manage savings transactions  | Savings transaction data   |
</Accordion>

***

## 🔑 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:

```http theme={null}
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:

```http theme={null}
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> 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>
<Note> 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**.</Note>

<Note> See [technical guide here](/guides/technical-guide) for how to calculate signature.</Note>

## 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:

| Error                  | Description                | Solution                                      |
| ---------------------- | -------------------------- | --------------------------------------------- |
| `invalid_client`       | Invalid client credentials | Check your client\_id and client\_secret      |
| `invalid_grant`        | Invalid authorization code | Ensure code is used only once and not expired |
| `invalid_redirect_uri` | Redirect URI mismatch      | Verify redirect URI matches registration      |
| `invalid_scope`        | Invalid scope requested    | Check scope format and permissions            |
| `access_denied`        | User denied consent        | Handle gracefully and retry                   |

<Note>
  Always implement proper error handling and provide clear feedback to users when authentication fails.
</Note>

## 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

<Button href="/quickstart" size="sm">
  Try the Quickstart Guide
</Button>