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

# Authentication Basics

> Overview of Niobi's cryptographic request signing model, required credentials, signature generation options, and dynamic endpoint parameters.

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

```mermaid theme={null}
%%{init: {'themeVariables': {'fontSize': '23px', 'actorBorder': '#0D9373', 'actorLineColor': '#0D9373', 'signalColor': '#0D9373', 'noteBorderColor': '#0D9373'}, 'sequence': {'width': 220, 'height': 95, 'actorMargin': 80, 'messageMargin': 60, 'boxMargin': 18, 'noteMargin': 18}}}%%
sequenceDiagram
    autonumber
    participant Merchant as Your Server
    participant Niobi as Niobi API

    Note over Merchant: 1. Assemble endpoint params, timestamp, and salt<br/>2. Compute unique signature with Secret Key<br/>3. Ensure Secret Key is not in final request
    Merchant->>Niobi: Send signed request envelope (client_id, sender, signature, params)
    Note over Niobi: Look up Secret Key for client_id<br/>Recalculate signature for this specific payload
    alt Signature matches
        Niobi-->>Merchant: 200 OK (payment initiated / processed)
    else Signature mismatch
        Niobi-->>Merchant: 403 Forbidden (request not verified)
    end
```

<Note>
  **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](/ip-whitelisting) for setup steps.
</Note>

***

## API Environments & Base URLs

Niobi provides dedicated Sandbox and Production environments. Configure your API client with the appropriate base URL:

| Environment    | Base URL                         | Purpose                                                |
| :------------- | :------------------------------- | :----------------------------------------------------- |
| **Sandbox**    | `https://sandbox.users.niobi.co` | Development, testing, and simulator verification.      |
| **Production** | `https://users.niobi.co`         | Live transaction processing and real money settlement. |

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**](/getting-credentials)), you will receive three credentials:

| Credential            | Field in Payload                 | Requirement                                     | Description                                                                                                                                        |
| :-------------------- | :------------------------------- | :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client ID**         | `client_id`                      | **Required** in every API request               | The unique identifier assigned to your integration in the Niobi Dashboard. Identifies your merchant account.                                       |
| **Integration Title** | `sender`                         | **Required** in every API request               | The exact name you gave to your integration when setting it up in the dashboard. Identifies the integration entity.                                |
| **Secret Key**        | `senderKey` *(used for signing)* | **Required for signing only** (Do not transmit) | Your private cryptographic key used on your backend server to compute the SHA-256 signature. **Never include this key in your final API request.** |

<Tip>
  **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](/getting-credentials) (includes UI video guide and key security practices) before proceeding with signature generation.
</Tip>

<Warning>
  **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.
</Warning>

***

## 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](/authentication/signature-generation#method-1-in-code) or via the [Niobi Signature Generation API](/authentication/signature-generation#method-2-signature-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:

<CardGroup cols={2}>
  <Card title="Method 1: In Code (Recommended for Production)" icon="code" href="/authentication/signature-generation#method-1-in-code">
    Implement our deterministic SHA-256 signing algorithm in your backend (Node.js, Python, PHP, Java, Go, etc.). Zero extra network latency.
  </Card>

  <Card title="Method 2: Niobi Signature Generation API" icon="bolt" href="/authentication/signature-generation#method-2-signature-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.
  </Card>
</CardGroup>

***

## 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](/authentication/signature-generation#verifying-response-signatures).

***

## Next Steps

Follow these two guides in order to complete your integration:

<div className="next-steps-flow">
  <a href="/authentication/signature-generation" className="next-step-card">
    <div className="next-step-badge">Step 1</div>
    <h3>How to Create the Signature</h3>
    <p>Implement the SHA-256 algorithm in code or use the Niobi Signature Generation API to compute your hash.</p>
  </a>

  <div className="next-step-arrow">
    <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path d="M5 12h14M12 5l7 7-7 7" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" />
    </svg>
  </div>

  <a href="/authentication/passing-signature" className="next-step-card">
    <div className="next-step-badge">Step 2</div>
    <h3>How to Pass Signature in Requests</h3>
    <p>Bundle your signature with endpoint parameters into the signed request envelope.</p>
  </a>
</div>