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

# Authentication

> All API requests must be authenticated using your API key, sent via the X-Numero-Api-Key header.

All API requests must be authenticated using your API key, sent via the `X-Numero-Api-Key` header.

## Getting your API keys

1. Sign in to your [Merchant Dashboard](https://merchant.usenumero.com)
2. Navigate to the **API Keys** section
3. Copy your **API Key** and **Public Key**

## Live and test keys

You get two secret keys, and **the key you send decides the mode** — there is no separate sandbox host or sandbox base URL:

| Key          | Mode     | Behaviour                                                                                                                           |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `live_key_…` | **Live** | Real money, real providers                                                                                                          |
| `test_key_…` | **Test** | Simulated providers and an isolated test wallet; live balances are never touched, and webhooks are delivered with `livemode: false` |

Develop against your `test_key_`, then swap in your `live_key_` — the base URL and every endpoint stay the same. See [Test mode](/05-test-mode).

> **Keep your keys safe.** API keys carry many privileges. Do not share them in public repositories, client-side code, or any publicly accessible location. You can rotate either key from the dashboard.

## Making authenticated requests

Include your API key in every request using the `X-Numero-Api-Key` header:

```bash theme={null}
curl -X GET "https://api.usenumero.com/numeroaccount/api/v1/business/balance" \
  -H "X-Numero-Api-Key: your_api_key_here"
```

## Request signing

Most `POST` endpoints require a request signature in addition to your API key. The signature is sent via the `X-Numero-Signature` header. This provides an extra layer of security by ensuring the request body hasn't been tampered with in transit.

See [Request Signing](/03-request-signing) for full details on how to generate signatures.

## Summary

| Header               | Required             | Description                               |
| -------------------- | -------------------- | ----------------------------------------- |
| `X-Numero-Api-Key`   | All requests         | Your merchant API key                     |
| `X-Numero-Signature` | POST requests (most) | HMAC-SHA256 signature of the request body |

## IP Whitelisting (Optional)

For additional security, you can restrict API access to specific IP addresses from your Merchant Dashboard. When enabled, requests from non-whitelisted IPs will be rejected. Both IPv4, IPv6, and CIDR notation (e.g., `192.168.1.0/24`) are supported.