Skip to main content
Every request to Rolla’s API is authenticated with an API key sent in the X-API-Key header:
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: 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).
Treat API keys like passwords: keep them server-side, out of client code and repositories, and rotate them if you suspect exposure.

​
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 and Rolla 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 for the full list of error codes.

​
Acting on tenant accounts

If your business uses the Platform 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.
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 product — see Operate Customer Accounts for the behaviour table and patterns, and Account Onboarding for creating accounts in your tenancy.