Permissions & scoping
A key holds an explicit list of allowed actions: wallet-scoped actions granted per wallet, plus a couple of global actions. The key can do exactly what you granted it, on exactly the wallets you chose.
Actions
| Action | Scope | Allows |
|---|---|---|
wallets:read | Wallet | See a wallet and list its addresses. |
balances:read | Wallet | Read a wallet’s balances. |
transactions:read | Wallet | Read a wallet’s deposits and withdrawals, and set review marks on them. |
withdrawals:read | Wallet | List and read a wallet’s withdrawals. |
wallets:update | Wallet | Rename a wallet and manage its addresses. |
wallets:delete | Wallet | Archive/delete a wallet. |
wallets:generate_address 🔑 | Wallet | Add new addresses to a wallet: derive them from the wallet secret, or have the server derive the next one when the wallet has an account xpub. |
withdrawals:request | Wallet | Propose a withdrawal from a wallet for a person to approve. Moves nothing on its own, so it needs no key of its own either. |
withdrawals:create 🔑 | Wallet | Prepare and broadcast withdrawals from a wallet. |
wallets:create | Global | Create new wallets and vaults. |
webhooks:manage | Global | Create, rotate, and delete webhooks. |
Per-wallet vs global
Wallet-scoped actions are granted on specific wallets: a key can hold withdrawals:create on one wallet and only balances:read on another, and is invisible to every wallet you didn't grant. The two global actions (wallets:create, webhooks:manage) aren't tied to a wallet.
Signing actions
withdrawals:request is not one of them, deliberately: asking for a payout moves nothing, so a key that only proposes needs no access to the wallet's key and can be granted by a member who holds none. That is the pair to reach for when an integration should be able to start a payout but never send one.
The 🔑 actions (withdrawals:create, wallets:generate_address) need the wallet's signing key. You can only grant them on wallets whose key you yourself hold, and a key that holds one of them can reveal that wallet's encrypted secret (GET /wallets/:id/secret, audited) so the SDK/CLI can sign or derive locally. The key acts as its creator, so if that member later loses access to the wallet's key, the key loses it too.
Least privilege
Grant the fewest wallets and actions that do the job: a key that only reads balances should hold just balances:read on the one wallet it watches. You can never grant an action you don't hold yourself, and every key change is audited in the company activity log.