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

## Roles & teams

Every member of your company holds one role. The role decides what they can administer and whether they may spend; a separate per-vault key-access grant decides which vaults they can actually sign for. Teams narrow what non-admin members can see.

### Roles

A company has five roles. Owners and admins run the organization and see every wallet; members do the day-to-day work; viewers read; signers sign. Members are invited from the dashboard (Company, then Members) and an invite that names no role joins as a `viewer`. Only owners can change a member's role or add another owner, and the last owner can never be removed or demoted.

- **owner**: full control, including billing, member roles and deleting the company.
- **admin**: everything an owner does except changing roles and adding owners.
- **member**: the ordinary operator. Reads its teams' wallets, requests withdrawals for someone to approve, generates deposit addresses, and builds integrations with API keys and webhooks. Never holds a vault key and never sends a withdrawal.
- **viewer**: read-only on its teams' wallets.
- **signer**: the only role besides owner and admin that can hold a vault key and send withdrawals, on its teams' wallets. Part of the Pro and Enterprise plans, which are the plans with teams.

### What each role can do

| Capability | `owner` | `admin` | `member` | `viewer` | `signer` |
| --- | --- | --- | --- | --- | --- |
| Read their teams' wallets, balances, transactions | ✓ | ✓ | ✓ | ✓ | ✓ |
| See every wallet regardless of team | ✓ | ✓ |  |  |  |
| Create, rename and archive vaults and wallets | ✓ | ✓ |  |  |  |
| Decide which teams a wallet belongs to | ✓ | ✓ |  |  |  |
| Generate deposit addresses (server-side, from the account xpub) | ✓ | ✓ | ✓ |  | ✓ |
| Register client-derived addresses (with key access on the vault) | ✓ | ✓ |  |  | ✓ |
| Request a withdrawal for someone to approve | ✓ | ✓ | ✓ |  | ✓ |
| Send withdrawals (with key access on the vault) | ✓ | ✓ |  |  | ✓ |
| Hold key access to a vault | ✓ | ✓ |  |  | ✓ |
| Share or revoke key access | ✓ | ✓ |  |  |  |
| Manage teams and team membership | ✓ | ✓ |  |  |  |
| Invite and remove members | ✓ | ✓ |  |  |  |
| Change a member's role, add owners | ✓ |  |  |  |  |
| Create API keys, manage webhooks | ✓ | ✓ | ✓ |  |  |
| Activity log, exports, billing | ✓ | ✓ |  |  |  |

> Sending funds needs three things at once: a role in the send row above, a key-access grant on the vault being spent from, and team access to the wallet itself. None is enough alone. Owners and admins see every wallet in the company but still cannot sign for a vault they have not been granted.

### Key access

A vault is one recovery phrase. Each member who may use it holds their own copy, encrypted to their personal key so the server never sees the phrase. Whoever creates a vault holds it from the start, and shares it with other members from the vault's key holders page in the dashboard, which re-encrypts the phrase for that member on their device. Viewers and members whose invite is still pending cannot receive a copy.

Sharing a key is a dashboard ceremony, not an API call, and it is two-sided. An owner or admin who already holds a copy seals one for the member and offers it; the member accepts or declines. Until they accept, nothing is in their account and they can sign for nothing. Both halves ask for a second factor, an unanswered offer expires after seven days, and the whole custody circle (everyone holding that key, plus the company's owners and admins) is emailed once it is accepted. API keys cannot read, offer, accept or remove key access at all.

Owners and admins can see the whole picture at once on the Organization map (Company, then Org map): every member, team, vault, wallet and API key, with a line for each team membership, key-access grant and API-key wallet grant. It is a dashboard view for the people who manage access, not an API-key endpoint.

Copies are removed explicitly per vault, and automatically in two cases: removing a member from the company deletes all of their grants, and changing a member's role to one that cannot hold a key (member or viewer) does the same. A member who is later promoted again starts with no vault access and must be re-granted, vault by vault. The last copy of a key cannot be removed, since nobody could sign for the vault again. Every offer, acceptance, decline, removal and secret read is recorded in the company activity log.

A share is also refused when it would be useless: a signer who cannot reach any of the vault's wallets through a team cannot be handed its phrase. Add them to a team that holds one first.

### Teams and visibility

A team holds a set of wallets, and its members see and act on exactly those. Every company has one default team. On the Developer and Startup plans it holds every member and wallet, so every member sees every wallet; on Pro and Enterprise people can also be kept off it. Pro (up to three teams, the default one included) and Enterprise (unlimited) unlock additional teams, moving people and wallets between them, and the `signer` role. On a plan below the cap, `POST /teams` answers `403`; the teams a company already has keep scoping their members whatever the plan does.

- Teams and their membership are managed by owners and admins (`/teams`). Owners and admins are never team-scoped: they see every wallet.
- A wallet's teams are set when it is created and changed with `PATCH /wallets/:id`. A wallet on no team is visible to owners and admins only.
- One wallet can belong to several teams, and a vault's wallets can be split across teams — custody is shared, access is not.
- A team that still has members, pending invites or wallets cannot be deleted, and the default team can never be deleted.
- `GET /teams` counts joined people in `memberCount` and invites not accepted yet in `pendingCount`: an invite puts its teams on record when it is sent, but the invitee sees nothing until they accept. `walletCount` counts active wallets the caller can read. `GET /teams/:id` lists each member with their `role` and `status` (`active` or `pending`).
- An archived team grants nothing, so it is never named on a wallet's `teams`.
- Teams change what members can see, not what they can spend. Sending stays role plus key access on top.
- Dropping off Enterprise never widens access: the teams you already have keep scoping their members, and only the writes that would widen access are refused.

### API keys and roles

An API key has no role of its own. It runs as the member who created it and can only be granted actions that member can perform at that moment (see Permissions & scoping). Owners, admins and members can create keys. The usual setup is a member creating a key for an integration: it can read, generate deposit addresses and request withdrawals, but it cannot send one, because a member holds no vault key. A key that sends needs an owner, admin or signer to create it, with a key-access grant on that vault. If the creator later loses the role, the grant, or their team access, the key loses the ability with them.

A key belongs to whoever created it: you manage your own, and owners and admins manage every key in the company, so a credential can still be retired when the person who made it has gone. Another member's key is not yours to edit or revoke.

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