Authentication
API keys, test and live mode, and the roles that decide what a key can do.
Every request carries a secret API key in the Authorization header:
curl https://api.monerail.com/v1/balance \
-H "Authorization: Bearer mr_live_3f9c…"A request without a valid key fails with 401 authentication_error.
Keys
| Prefix | Mode | Works on |
|---|---|---|
mr_test_ |
Test | Test objects only. No real money moves. |
mr_live_ |
Live | Real money. Available once your business verification is approved. |
Create keys in the dashboard under Developers › API keys. Only an Owner or a Developer can create one, and two-factor authentication must be on for their account. A key has a name of 2 to 60 characters. The full key is shown once: Monerail stores only a hash of it. You can have up to 20 active keys, and revoke any of them at any time; a revoked key stops working immediately.
The dashboard switches between modes with the Test | Live selector in the header. Live mode stays locked until your business verification is approved; live keys and live webhook endpoints need it too.
Keep keys on your server. Never put a key in a website, a mobile app or a public repository. Load it from an environment variable or a secret manager, and revoke it straight away if it leaks. See Security.
What a key can do
A key acts on behalf of the team member who created it, with that member’s role. If their role changes, the key follows. If they leave the business, the key stops working (401 api_key_owner_removed): create a new one.
| Operation | Roles allowed |
|---|---|
| Read balance, collections, payouts, settlements, transactions, cardholders, cards, operators, banks | Every role |
| Read events | Owner, Finance, Developer |
| Read webhook endpoints | Owner, Developer |
| Create collections, send codes | Owner, Finance, Developer |
| Create payouts | Owner, Finance, Approver |
| Create settlements | Owner, Finance |
| Create cardholders, verify them, issue cards | Owner, Finance |
| Fund, withdraw, terminate cards | Owner, Finance |
| Freeze, unfreeze cards | Owner, Finance, Approver |
| Create webhook endpoints | Owner, Developer |
| Delete webhook endpoints, redeliver events | Owner, Developer |
| Card test helpers | Owner, Finance |
The roles are Owner, Finance, Approver, Developer and Viewer. A Viewer can only read, and neither an Approver nor a Viewer can read events. An operation outside the role fails with 403 permission_denied. A good practice: create the key used in production from a dedicated member account with only the role your integration needs.
Response headers
| Header | Meaning |
|---|---|
Request-Id |
Unique ID of the request (req_…). Give it to support. |
Monerail-Version |
API version that produced the response. |
Idempotent-Replayed |
true when the response is a replay of an earlier request with the same Idempotency-Key. |
Retry-After |
On 429, seconds to wait before retrying. |
Strict-Transport-Security |
Forces HTTPS: the API never answers over plain HTTP. |
X-Content-Type-Options |
nosniff. |
Language
Error messages are in English. Send Accept-Language: fr to get them in French. Codes never change with the language.