> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesh.larkwave.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, IP allowlists, permissions and features.

Every request sends your key in the `X-Api-Key` header, from an IP address on that key's allowlist. Callers are servers; there is no login.

```bash theme={null}
curl https://$MESH_HOST/v1/status -H "X-Api-Key: lsk_test_AbC123.s3cr3t…"
```

> [!WARNING]
>
> Keep keys on your servers. Never put one in a browser, a mobile app or a repository.

## Keys

Your bank's merchant portal issues and revokes keys. A key looks like `lsk_<mode>_<public id>.<secret>`:

| Prefix | Mode | Reaches |
| - | - | - |
| `lsk_test_` | Test | The bank's sandbox: simulated money and identity results |
| `lsk_live_` | Live | The bank's real rails. Works once the bank has approved your business |

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 same `401` 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:write` or `accounts:read`. A missing permission is `403` (code `15`).
* **Your business's feature** for the route, which your bank switches on (for example `VIRTUAL_ACCOUNTS`, `WALLETS`, `TRANSFERS_INTERBANK`). A feature that's off is `403` (code `43`).

`GET /v1/status` lists the key's permissions. Switching a feature off takes effect on the next request; keys don't need reissuing.

| Permission | Routes |
| - | - |
| `customers:read`, `customers:write` | Customers |
| `kyc:read`, `kyc:write` | Verifications |
| `wallets:read`, `wallets:write` | Wallets |
| `virtual-accounts:read`, `virtual-accounts:write` | Virtual accounts, payments, simulations, number patterns |
| `accounts:read` | Balances, transactions, limits, banks and account names, transfer status |
| `transfers:write` | Transfers and settlements |
| `events:read` | Events |
| `webhooks:manage` | Webhook URL and deliveries |

## Failures

Every authentication failure is the same `401` (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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.