> Guveno API reference v1.10.0, last updated October 17, 2026. The whole reference is at https://www.guveno.com/llms-full.txt.

## 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.

Source: https://www.guveno.com/docs/roles/