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

# Authentication

> Secure your API requests with Bearer Secret Keys

# API Authentication & Security

Handle uses **Bearer Token Authentication** over **TLS 1.3** to authenticate all API requests.

```http theme={null}
Authorization: Bearer sk_live_...
Content-Type: application/json
```

## API Key Types

| Key Prefix    | Environment           | Purpose                                                               |
| :------------ | :-------------------- | :-------------------------------------------------------------------- |
| `sk_live_...` | **Production (Live)** | Debits real bank accounts and executes real NIP merchant settlements. |
| `sk_test_...` | **Sandbox (Test)**    | Simulates charges, pushes, and webhooks with zero real funds moved.   |

<Note>
  Secret keys are hashed using `SHA-256` before being stored in the Handle database. Handle will never display your secret key again after initial generation. Keep it stored securely in your `.env` file or secret manager.
</Note>

***

## Request Idempotency (`X-Idempotency-Key`)

To prevent accidental double-billing if network connection drops during an API call, you can pass a unique `X-Idempotency-Key` header:

```http theme={null}
POST /v1/charges/dispatch
Authorization: Bearer sk_live_...
X-Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
```

If you retry a request with the exact same idempotency key, Handle returns the saved original response instead of re-debiting the customer.

***

## IP Whitelisting & Domain Security

For enterprise merchants, you can lock your API keys to specific production server IP addresses in the [Handle Merchant Dashboard](https://admin.handle.ng/developers). Requests originating from unlisted IP addresses are rejected with `403 Forbidden`.