Skip to main content

​
Overview

To maintain the highest level of security and data integrity across all transactions, Niobi requires cryptographic request signing for all API communication. Unlike APIs that use static API tokens or reusable session headers, every individual request sent to any Niobi endpoint must be signed uniquely. Because each signature is cryptographically computed from the request’s exact timestamp, a random salt, and the specific payload parameters (params), signatures cannot be reused across multiple requests. If any parameter changes, or when initiating a new transaction, a fresh signature must be generated.
Pre-requisite: IP Whitelisting
Before sending any API requests to Niobi servers or endpoints (in Sandbox or Production), your server’s outgoing public IP address must be whitelisted in the Niobi Dashboard under Workspace -> IP Whitelisting. Requests sent from non-whitelisted IPs will be blocked. See our IP Whitelisting Guide for setup steps.

​
API Environments & Base URLs

Niobi provides dedicated Sandbox and Production environments. Configure your API client with the appropriate base URL: Prepend the appropriate base URL to all endpoint paths described in the documentation (e.g. https://sandbox.users.niobi.co/api/v4/niobi-unified-collections for sandbox testing).

​
Core Credentials

When you create an API integration in your Niobi Dashboard (under Workspace -> Integrations), you will receive three credentials:
Need to generate your API credentials first?
If you have not created an integration in your dashboard yet, follow our step-by-step walkthrough in Getting Your API Credentials (includes UI video guide and key security practices) before proceeding with signature generation.
Never expose your Secret Key in client-side code (such as React, Vue, iOS, or Android apps) or send it in raw HTTP requests. Request signing must always occur on your secure backend server.

​
How Credentials and Request Parameters (params) Connect

Whenever your system interacts with a Niobi endpoint (for example, collecting a payment or initiating a payout):
  1. Package Target Parameters: Place all the specific fields required by that destination endpoint inside a nested "params": { ... } object (such as amount, currency, mobile, payment_method_type, etc.).
  2. Attach Authentication Metadata: Bundle params with your integration credentials (client_id, sender), the UNIX timestamp (in seconds) at the time of signing, and a random salt (a unique string generated on your server as an additional layer of security and entropy).
  3. Generate the Signature: Sign that specific combination using your private Secret Key (either in your code or via the Niobi Signature Generation API).
  4. Dispatch the Request: Send the signed envelope to the destination endpoint. Niobi recalculates the hash and confirms that the payload was created by you and has not been altered in transit.

​
Two Ways to Generate Signatures

Niobi gives you two flexible ways to generate request signatures:

Method 1: In Code (Recommended for Production)

Implement our deterministic SHA-256 signing algorithm in your backend (Node.js, Python, PHP, Java, Go, etc.). Zero extra network latency.

Method 2: Niobi Signature Generation API

Call Niobi’s dedicated POST /api/niobi-signature endpoint to automatically generate and return a signed payload. Ideal for rapid prototyping and Postman testing.

​
Response & Callback Verification

Security is bidirectional. When Niobi sends a synchronous response or an asynchronous webhook callback to your server, the payload includes a signature computed by Niobi. You can verify this signature on your server to guarantee that the incoming callback genuinely originated from Niobi and was not intercepted or altered in transit. Detailed steps are covered in Response Signature Verification.

​
Next Steps

Follow these two guides in order to complete your integration:
Step 1

​
How to Create the Signature

Implement the SHA-256 algorithm in code or use the Niobi Signature Generation API to compute your hash.

Step 2

​
How to Pass Signature in Requests

Bundle your signature with endpoint parameters into the signed request envelope.