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

# Authentication

> Authenticate every API request using your secret API key as a Bearer token.

## Header Format

All requests must include your API key in the `Authorization` header:

```
Authorization: Bearer rtu_live_sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

RapidTopup supports two environment key formats:

* **Live Keys:** Begin with `rtu_live_sk_` (invokes live transactions and deducts real wallet balance).
* **Test (Sandbox) Keys:** Begin with `rtu_test_sk_` (routes requests to the isolated mock sandbox environment without spending real funds).

***

## Example Request

```bash cURL theme={null}
curl --request GET \
  --url https://api.rapidtopup.com.ng/api/v2/b2b/balance \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer rtu_live_sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
```

```javascript JavaScript (Fetch) theme={null}
const response = await fetch('https://api.rapidtopup.com.ng/api/v2/b2b/balance', {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'Authorization': `Bearer ${process.env.RAPIDTOPUP_API_KEY}`,
  },
});

const data = await response.json();
console.log(data.data.balance); // "45000.50"
```

```php PHP (Guzzle) theme={null}
<?php

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('GET', 'https://api.rapidtopup.com.ng/api/v2/b2b/balance', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer ' . env('RAPIDTOPUP_API_KEY'),
    ],
]);

$data = json_decode($response->getBody(), true);
echo $data['data']['balance']; // "45000.50"
```

***

## Key Security Rules

> [card] Store as environment variable
>
> ```bash theme={null}
> RAPIDTOPUP_API_KEY=rtu_live_sk_...
> ```
>
> Never hardcode keys in source files.

> [card] Server-side only
>
> Keys must only be used from your backend. Never expose them in frontend JavaScript or mobile apps.

> [card] Rotate if compromised
>
> Revoke the key immediately from the Developer Dashboard and generate a new one.

> [card] Up to 5 active keys
>
> You can maintain up to 5 active API keys per environment (5 live, 5 test).

***

## Authentication Errors

| Response Code | Meaning |
| - | - |
| `401 Unauthorized` | Key is missing, malformed, or has been revoked |
| `403 Forbidden` | Key is valid but your account is suspended |

```json theme={null}
{
  "status": "error",
  "message": "Unauthorized. Invalid or missing API key format."
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.