Security

Protect your keys, your webhooks and your customers’ money.

Your API key can move money. Treat it like a bank password, and treat every webhook as untrusted until its signature is checked.

Keep keys on your server#

• Call the API only from your server. Never from a web page, a browser extension or a mobile app: anyone can read a key shipped to a device. Your app talks to your server, your server talks to Monerail.
• Load the key from an environment variable or a secret manager. Never commit it, never paste it in a ticket or a chat.
• Use test keys (mr_test_) everywhere except production. In your tests, check "livemode": false on what you receive.
• Name each key after where it is used (2 to 60 characters), so you know which one to revoke.

Give each key the smallest role#

A key acts with the role of the member who created it (table). Create production keys from a dedicated member account with only the role the integration needs:

Rotate and revoke#

• To rotate a key: create the new key, deploy it, check that traffic uses it, then revoke the old one. You can have up to 20 active keys, so both can live side by side for a while.
• A revoked key stops working immediately.
• When a member leaves the business, every key they created stops working (401 api_key_owner_removed). Plan replacements before removing someone.
• Rotate keys when someone who had access to them leaves your team, and right away if a key may have leaked.

Verify every webhook#

• Verify the signature of every event with the endpoint secret, over the raw body, with a constant-time comparison, and refuse timestamps older than 5 minutes.
• Use an HTTPS URL with a domain name. Monerail refuses IP addresses and URLs with user:password@, and never delivers to private, loopback, link-local or reserved addresses.
• The secret is shown once. To rotate it, create a second endpoint with the same URL, accept both secrets for a while, then delete the old endpoint. Deduplicate events by id: during the overlap, each event arrives twice.

Never pay twice#

Send an Idempotency-Key on every POST that moves money (collections, payouts, settlements, card issuing and funding), and reuse the same key when you retry. Treat 202 as “on its way”: never create the operation again, wait for the webhook.

Transport and logs#

• The API is HTTPS only and sends Strict-Transport-Security. Keep certificate verification on in your HTTP client.
• Log the Request-Id of every call. Never log the Authorization header, webhook secrets or identity documents.
• Error messages are written for developers and never contain internal or partner details. Show your own messages to your customers.

What Monerail does#

• Stores only a hash of each API key; the full key is shown once.
• Requires two-factor authentication to create API keys.
• Checks the role of the key before acting, and before storing any identity document.
• Signs every webhook with HMAC-SHA256 and a timestamp, and blocks deliveries to private addresses.
• Limits request rates per key and per business (Rate limits).
• Never returns full card numbers or CVCs through the API. An Owner or Finance member can display them for 60 seconds in the dashboard.
• Verifies identities per business: a person verified by another business is verified again for yours.
• Lets only an Owner change settlement accounts, in the dashboard; the API cannot.

To report a security problem, write to support@monerail.com.