Step-by-step guides
API keys and authentication, step by step
Private key, public key and VAS key: which one each endpoint needs, how to get, store and rotate them, and how IP whitelisting for payouts works.
The four credentials
Every request names who you are with X-API-USER (your Moolre username) and proves it with one key. Which key you send depends on what you call. Keys belong to a wallet: a key created for one wallet cannot act on another, and live keys never work in the sandbox (or the other way round).
Always send credentials in request headers. Keys or usernames in the URL or in the request body still work for now, but they are deprecated, they end up in access logs, and each response carries a notice. See Deprecations.
| Header | Key | Use it for | Keep it |
|---|---|---|---|
| X-API-USER | Username | Every request | In config; not secret on its own |
| X-API-KEY | Private key | Payouts and transfers, validate name, accounts and statements, bulk payouts, invoices, webhook tools, sales (airtime and data) | On your server only. It can move money |
| X-API-PUBKEY | Public key | Collections (Mobile Money Collection), Payment IDs, payment links, hosted checkout and the JavaScript inline plugin | On your server for API calls. It can start collections but cannot move money out |
| X-API-VASKEY | VAS key | SMS and WhatsApp. SMS and WhatsApp each have their own key | On your server only |
Which one for this endpoint?
Each API reference page lists its headers. As a rule: money out and account data need the private key, money in needs the public key, and messaging needs the VAS key for that service. Bulk payouts, invoices and webhook tools refuse a public key.
Step by step: get your keys
- Sign in to the Moolre app and open the wallet you will integrate.
- Create an API Service linked to that wallet. Credentials are tied to the wallet behind the service, so repeat this for every wallet you use.
- Generate the credentials you need: the private key, the public key, and a VAS key for each messaging service. The key is shown when you generate it: copy it into your secret manager straight away.
- Switch API access on for the wallet. Without it every call returns AIN04 (API Access not activated).
- Set the wallet callback URL if you want webhooks (Update Account).
- Make one harmless call to prove the keys work: Account Status with your private key, or Validate Name.
curl https://api.moolre.com/open/account/status \ -H "Content-Type: application/json" \ -H "X-API-USER: $MOOLRE_USER" \ -H "X-API-KEY: $MOOLRE_KEY" \ -d '{ "type": 1, "accountnumber": "1000000000001" }'Step by step: store and use keys safely
- Put keys in environment variables or a secret manager. Never in source control, never in a mobile app or browser, never in a support ticket.
- Load them once at start-up and pass them to your HTTP client as headers. Do not log request headers.
- Use separate keys for sandbox and live, and make the environment a single setting (MOOLRE_ENV=sandbox|live) that also chooses the base URL.
- Keep the private key out of any process that does not need to pay out. A service that only collects needs only the public key.
- Log the meta.requestid of every call, never the key.
const BASES = { sandbox: 'https://sandbox.moolre.com', live: 'https://api.moolre.com' };const base = BASES[process.env.MOOLRE_ENV ?? 'sandbox'];async function moolre(path, body, { key = 'private', idempotencyKey } = {}) { const headers = { 'Content-Type': 'application/json', 'X-API-USER': process.env.MOOLRE_USER, ...(key === 'private' ? { 'X-API-KEY': process.env.MOOLRE_KEY } : { 'X-API-PUBKEY': process.env.MOOLRE_PUBKEY }), ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}), }; const res = await fetch(base + path, { method: 'POST', headers, body: JSON.stringify(body) }); const json = await res.json(); console.log('moolre', path, json.code, json.meta?.requestid); // the request id, never the key return json;}Step by step: rotate a key
Rotate on a schedule, when someone with access leaves, and immediately if a key may have leaked.
- Generate a new key for the API Service in the Moolre app.
- Put the new key in your secret manager and deploy it to every service that uses it.
- Make a harmless call (Account Status) from each service and confirm the response is not an authentication error (AIN01, AIN05).
- Treat the old key as revoked: remove it from every store and every laptop.
- Watch the next hour of logs for AIN05. A service you forgot will show up there.
Public keys can be re-signed
A response may carry the PUBKEY_RESIGN notice: your public key was signed with a retiring key. Generate a new public key before the date in the notice. The old one keeps working until then.
IP whitelisting for payouts
Payouts are disbursements, so they are also restricted by IP address. Add the public addresses of the servers that send payouts to the whitelist for the wallet in the Moolre app. A payout, a bulk payout or an invoice action from an address that is not on the list is refused with code TK01, even with a correct key.
Add every address you will send from, including your staging and your failover. Cloud and serverless platforms often change addresses: use a NAT gateway or a fixed egress address.
- Find your server's public IP (what a remote service sees): for example curl https://api.ipify.org from that server.
- In the Moolre app open the wallet security settings and choose Whitelist IP for Disbursement.
- Add the address, save, and send a small payout from that server.
- Repeat for every environment that sends payouts.
Authentication errors and fixes
| Code | Meaning | Fix |
|---|---|---|
| AIN01 | Authentication error: the user or key is wrong, or no credentials were sent | Check X-API-USER and the key header, and that the key matches the environment |
| AIN02 | accountnumber is required | Send accountnumber on endpoints that act on a wallet |
| AIN03 | Wallet not found | Check the account number and that the wallet belongs to this user |
| AIN04 | API access not activated | Switch API access on for the wallet |
| AIN05 | Credentials rejected for this wallet | Use the key generated for this wallet; check the environment |
| AIN06 | No body and no credentials | Send a JSON body and the headers |
| AIN11 | VAS key missing or rejected | Use the SMS or WhatsApp key for that service |
| TK01 | IP not whitelisted for disbursements | Add the server address to the whitelist |
- Keys are only in headers, never in URLs or bodies.
- Private and VAS keys are server-side only.
- Sandbox and live keys are separate and the environment is one setting.
- The wallet has API access on and the payout IPs are whitelisted.
- A rotation date is in your calendar.