Addresses, folders, and access

Every address is a leaf of the Vault's tree and, at the same time, an account in the ledger. On the Vaults and derivation page, we covered how addresses come into being; here we look at how they're organized into folders and who gets access to them.

An address is an account

An address has a derivation path, a network, and a primary token. It receives and sends funds, and its balance is split into available and reserved (see the ledger for details). Every address has an owner: the person who created it.

• GET /api/v1/vaults/{code}/addresses lists the Vault's addresses, with the search, token (primary token), and access=shared (only what's shared with you) filters.
• GET /api/v1/vaults/{code}/addresses/{id} returns the details of a single address: its balance and recent operations.
• PATCH /api/v1/vaults/{code}/addresses/{id} updates an address (for example, renames it).

Address creation is covered on the Vault page, along with segments and derivation paths.

Folders: addresses under one roof

A folder is a named set of addresses. It's handy when you need to manage access and accounting for a group of addresses rather than one at a time, for example, "all of a client's addresses" or "all invoicing addresses."

• POST /api/v1/vaults/{code}/address-folders creates a folder.
• POST /api/v1/vaults/{code}/address-folders/{id}/members adds an address to a folder.
• GET /api/v1/vaults/{code}/address-folders/{id} returns the folder's contents and the grants issued on it in a single response.

A folder has an owner, the "manager" (an address's owner is its creator).

Access is granted through roles

Permissions on both addresses and folders are defined by a role:

The permission to create addresses (canCreateAddress) isn't part of any role and is granted separately.

There are two ways to grant access:

• Per address: POST /api/v1/vaults/{code}/addresses/{id}/shares. The single form issues one grant; the batch form (subjects[]) grants access to several subjects at once.
• To an entire folder: POST /api/v1/vaults/{code}/address-folders/{id}/grants. The subject gets permissions on all of the folder's addresses, including ones added later: a new address in the folder is automatically accessible to everyone the folder is shared with.

The subject of a grant can be a user or a user group. A grant to a group gives access to all of its members; it's revoked by leaving the group, not individually.

Example: give a colleague access to an address with transfer permissions.

curl -X POST "[BASE_URL]/api/v1/vaults/demo_vault/addresses/ADDRESS_ID/shares" \
  -H "Authorization: Bearer $V3_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "subjectType": "user", "subjectId": "USER_ID", "role": "contributor" }'

await fetch("[BASE_URL]/api/v1/vaults/demo_vault/addresses/ADDRESS_ID/shares", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.V3_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ subjectType: "user", subjectId: "USER_ID", role: "contributor" }),
});

requests.post(
    "[BASE_URL]/api/v1/vaults/demo_vault/addresses/ADDRESS_ID/shares",
    headers={"Authorization": f"Bearer {os.environ['V3_TOKEN']}"},
    json={"subjectType": "user", "subjectId": "USER_ID", "role": "contributor"},
)

And here's how to share an entire folder with a user group for viewing:

curl -X POST "[BASE_URL]/api/v1/vaults/demo_vault/address-folders/FOLDER_ID/grants" \
  -H "Authorization: Bearer $V3_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "subjectType": "group", "subjectId": "USER_GROUP_ID", "role": "viewer" }'

await fetch("[BASE_URL]/api/v1/vaults/demo_vault/address-folders/FOLDER_ID/grants", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.V3_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ subjectType: "group", subjectId: "USER_GROUP_ID", role: "viewer" }),
});

requests.post(
    "[BASE_URL]/api/v1/vaults/demo_vault/address-folders/FOLDER_ID/grants",
    headers={"Authorization": f"Bearer {os.environ['V3_TOKEN']}"},
    json={"subjectType": "group", "subjectId": "USER_GROUP_ID", "role": "viewer"},
)

Which to choose: address, folder, or group

The three methods solve different problems:

• Per address: when you need one-off access to a single address.
• Per folder: when you have a set of addresses and need access to all of them, including future ones (the grant covers new addresses automatically).
• To a user group: when access is role-based: you grant it to a team or role and manage membership (add a person and they get access; remove them and it's gone).

The methods can be combined: you can share a folder with a user group, and then all of the folder's addresses are accessible to all members of the group.

Who got access and from where

Access to a single address can come from different sources: a personal grant, a folder, or a user group:

That's why it matters to see not the grants themselves, but the people and where each person's access comes from:

• GET /api/v1/vaults/{code}/addresses/{id}/participants returns the list of people with access to an address: user groups are expanded, folder access is included, and the owner is returned separately.

The via field explains the source of access and therefore how to remove it:

Related lists are easy to mix up. Here's what each one returns:

Visibility is isolated by default

Access answers "what can you do," while visibility answers "what can you see at all." By default, a regular member sees only their own addresses, operations, and balances; an administrator sees the entire Vault. Permissions are applied before aggregation, so other members' data doesn't leak even into totals.

An administrator can expand visibility selectively:

• POST /api/v1/vaults/{code}/visibility-grants specifies who (subjectType: user|group) and whose data they see (scope: self|group|vault). For example, you can give a compliance role visibility across the entire Vault.

Terms

Next steps