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

# Authentication

> API keys, IP allowlisting, and tenant account scoping

Every request to Rolla's API is authenticated with an API key sent in the `X-API-Key` header:

```bash theme={null}
curl "https://api.rolla.xyz/api/v1/external/wallet/wallets" \
  -H "X-API-Key: your_api_key_here"
```

A missing key returns `401 API key missing`; an unknown or revoked key returns `401 Invalid or inactive API key`.

## Managing API keys

Keys are created and managed in the dashboard under **Settings → API Keys**. When you create a key you choose:

| Setting             | Meaning                                                                                       |
| ------------------- | --------------------------------------------------------------------------------------------- |
| **Label**           | A name so you can tell keys apart                                                             |
| **Allowlisted IPs** | The IP addresses the key may be used from — required before the key can move money, see below |

The key value is shown **once** at creation. Rolla stores only a hash of it, so a lost key cannot be recovered — regenerate it instead (the old value stops working immediately).

<Warning>
  Treat API keys like passwords: keep them server-side, out of client code and repositories, and rotate them if you suspect exposure.
</Warning>

## IP allowlisting

An allowlist is enforced in two ways, and it's worth keeping both in mind:

* **Once a key has an allowlist, it applies to every endpoint** — there's no read-only exception. Requests from any other IP are rejected with `403 IP address <ip> not authorized`.
* **Money movement requires one.** [Withdraw Funds](/api-reference/endpoint/wallet/withdraw) and [Rolla Transfer](/api-reference/endpoint/wallet/transfer) refuse a key with no allowlisted IP at all, with `403 This endpoint requires IP whitelisting. Add at least one whitelisted IP to your API key before using withdraw.` Every other endpoint is callable from anywhere while the key's allowlist is empty.

Give every production key an allowlist — it's the only thing standing between a leaked key and your balances.

If your server sits behind a proxy or NAT, allowlist the egress IP your requests actually leave from. The dashboard's API Keys page can show you the IP you're currently calling from.

## Account status requirements

Beyond the key itself, the business it belongs to must be in good standing:

* API access must be enabled for the account (`403 API access has been disabled for this account` otherwise)
* The account must not be deactivated or blacklisted — those receive `403 There is a problem with your account. Please contact Support for assistance.` with the code `ACCOUNT_RESTRICTED` and `accountBlocked: true`
* A deleted account receives `401 Account does not exist.` with the code `ACCOUNT_DOES_NOT_EXIST`

See [Errors](/concepts/errors) for the full list of error codes.

## Acting on tenant accounts

If your business uses the [Platform](/platform/overview) product (a **white-label tenant**), a single API key can act on any account inside your tenancy by adding the optional `X-Account-Id` header. The entire request — wallets, payouts, documents, everything — then runs as that account.

```bash theme={null}
curl "https://api.rolla.xyz/api/v1/external/wallet/wallets" \
  -H "X-API-Key: your_tenant_api_key" \
  -H "X-Account-Id: 3f1c2d4e-5a6b-7c8d-9e0f-1a2b3c4d5e6f"
```

The header must be a valid account UUID (`400` otherwise). A key that isn't a tenant key is refused with `403 X-Account-Id is only available to tenant API keys`, and an account that isn't in your tenancy — including one that doesn't exist — with `404 Account not found in your tenancy`.

This is the heart of the [Platform](/platform/overview) product — see [Operate Customer Accounts](/platform/operate-accounts) for the behaviour table and patterns, and [Account Onboarding](/api-reference/endpoint/accounts/overview) for creating accounts in your tenancy.