X-Api-Key header, from an IP address on that key’s allowlist. Callers are servers; there is no login.
Keys
Your bank’s merchant portal issues and revokes keys. A key looks likelsk_<mode>_<public id>.<secret>:
A key belongs to exactly one business, so you never send a business id: Mesh takes it from the key and ignores any you send.
IP allowlist
Each key is used only from the addresses registered for it in the portal. A call from anywhere else is refused with the same401 as a wrong key. With no addresses registered, a key can’t be used at all.
What a key may do
A call succeeds when both hold:- The key’s permission for the route, for example
virtual-accounts:writeoraccounts:read. A missing permission is403(code15). - Your business’s feature for the route, which your bank switches on (for example
VIRTUAL_ACCOUNTS,WALLETS,TRANSFERS_INTERBANK). A feature that’s off is403(code43).
GET /v1/status lists the key’s permissions. Switching a feature off takes effect on the next request; keys don’t need reissuing.
Failures
Every authentication failure is the same401 (code 14), whatever the cause: no key, an unknown or revoked key, the wrong address, or a business the bank has suspended. That way a failure never tells an attacker which part was wrong. If you get a 401 you didn’t expect, check the key and your server’s outgoing IP address in the portal.