Introduction
Learn how to ensure secure access to Nomba API Resources.
Overview
OAuth 2.0 stands as a pivotal mechanism for merchants to obtain valid access_token from the Nomba API Server, providing a framework for secure and efficient interactions with our platform. Within this protocol, two distinct processes, namely the Client-credentials flow and the PKCE flow flow, offer versatile approaches to acquiring the access_token
Quick Action
Obtain access token
Generate access_token required to access resources
Refresh access token
Refresh access_token when they get expired
Revoke access token
Revoke access_token from accessing resources
Client-credentials flow
This flow is specifically tailored for execution on the merchant’s server or backend infrastructure. The process unfolds as follows:
Initiation of Token Request
The merchant’s server, residing in the backend, initiates the token request by invoking the IssueToken endpoint on the Nomba API. This request includes the client_id and client_secret, credentials obtained from the merchant’s Nomba dashboard.
Token request initiation
Token Issuance by Nomba
Nomba diligently validates the provided client_id and client_secret against its records. Upon successful validation, Nomba issues an access_token accompanied by a refresh_token. These tokens empower the merchant’s server to make authorized API calls on behalf of the client.
Refreshing your access_token
PKCE flow
The PKCE flow also known as the Proof Key for Code Exchange, is not yet available for public use
This flow is strategically designed for execution on the merchant’s client or frontend infrastructure. The emphasis here is on securing the handling of credentials, particularly avoiding the use of the Client-credentials flow on the client side due to the potential exposure of the client secret. The PKCE flow addresses this concern and ensures secure authentication and authorization of a merchant’s client.
Implementing the OAuth 2.0 PKCE flow involves additional steps compared to the Client-credentials flow, making it a suitable choice for frontend environments where the handling of sensitive information requires heightened security measures.
Merchants are encouraged to exercise best practices in selecting the appropriate flow based on their specific infrastructure needs. By leveraging OAuth 2.0, merchants establish a robust and secure connection between their systems and the Nomba API Server, promoting a seamless and trustworthy integration that aligns with modern security standards and practices.
The PKCE (Proof Key for Code Exchange) flow is a security enhancement for OAuth 2.0 authorization that is specifically designed for public clients (e.g., mobile applications) to protect against authorization code interception attacks. Let’s break down the PKCE flow:
Client Generates Code Verifier and Code Challenge
The client initiates the PKCE flow by generating a random code_verifier.
From this code_verifier, the client then computes a code_challenge. Typically, the code_challenge is the Base64-encoded SHA256 hash of the code_verifier, as specified in Page 17 of RFC 7636
Client Sends Code Challenge to Authorize Endpoint
The client includes the code_challenge when making a request to the PKCE authorization endpoint of the Nomba API. This is part of the initial step in the OAuth 2.0 authorization process.
Nomba Returns Auth Code
Upon successful processing of the authorization request, we returns an auth_code. The auth_code serves as a temporary authorization code that the client will exchange for an access_token.
Client Calls IssueToken Endpoint
The client proceeds to call the IssueToken endpoint with the obtained auth_code and the original code_verifier.
Nomba Verifies auth code, Code Verifier and Issues Tokens
Nomba receives the request to IssueToken and verifies that the code_verifier matches the code_challenge associated with the auth_code. If the verification is successful, Nomba issues the requested access_token along with a refresh_token.
This PKCE flow enhances security by ensuring that the authorization code obtained by the client cannot be easily intercepted and misused, as the original code_verifier is required during the token exchange.
PKCE flow
How Authentication Works
When an API Key is generated through the Nomba dashboard, it assumes a role within the organizational framework, akin to being a designated member of the team. This API Key serves as the essential credential for authenticating and authorizing access to the organization’s resources. Its functionality mirrors that of a regular user who uses an email and password for accessing organizational assets. Importantly, the creation of multiple API Keys is supported, providing the flexibility needed for specific use cases. Moreover, the system allows for the suspension or revocation of API Keys, offering a dynamic control mechanism over access privileges.
Authentication Requirements
To successfully authenticate, the API Key necessitates the provision of both the client_id and client_secret. These credentials act as a secure handshake, validating the identity of the API Key holder. This authentication process is pivotal in obtaining a valid token, a digital key that grants access to the organization’s resources. The requirement for both client_id and client_secret ensures a robust authentication mechanism, enhancing the overall security posture.
Token Retrieval and Authorization
The authenticated API Key, armed with the valid token, is then empowered to authorize subsequent requests for accessing the organization’s resources. This token, often referred to as a bearer token, serves as the digital key that unlocks the door to various functionalities and data within the organizational ecosystem. It acts as a time-limited, revocable permission slip, ensuring that access remains secure and controlled.
API Key Management and Permission Privileges
The ability to create multiple API Keys introduces a layer of flexibility, enabling organizations to tailor access privileges to specific roles or functionalities. Each API Key is endowed with permission privileges, defining the scope of its actions. By default, an API Key is bestowed with Admin permissions upon creation, providing a broad spectrum of access to organizational resources. This includes the capacity to create accounts, manage transaction records, assign terminals, and initiate transfer transactions. This default setting streamlines the integration process while allowing for nuanced customization based on organizational requirements.
Identity and Access Management (IAM) System
Integral to Nomba’s security framework is its Identity and Access Management (IAM) system. This system ensures the effective and secure control of access to resources within the organization. It delineates roles and permissions, dictating what actions each API Key can perform. The IAM system operates as a gatekeeper, enforcing necessary access restrictions and fostering a secure and organized structure.
Impact of Suspension or Revocation
In scenarios where security concerns arise or changes in access requirements transpire, the suspension or revocation of an API Key becomes a pivotal control measure. By suspending or revoking an API Key, organizations promptly nullify its ability to perform functions or access resources. This responsive approach fortifies the organization against potential security threats or unauthorized access, contributing to a proactive security stance.
Conclusion
Nomba’s API Key authentication process is a comprehensive and layered system, balancing flexibility, security, and control. From API Key creation and authentication requirements to token retrieval, permission management, and IAM enforcement, each facet is meticulously designed to provide organizations with a secure, customizable, and efficient means of managing access to their valuable resources.