Access model

How V3 Custody decides what you can do and what you can see: group membership, default-deny, address roles, and visibility isolation.

Authentication answers "who are you," while the access model answers "what are you allowed to do" and "what can you see." Three layers combine; tokens have no separate scopes:

Layer	What it determines	Mechanism
group membership	which actions are allowed	Policy Engine, default-deny
address and folder grants	roles on specific addresses	`viewer` / `contributor`
visibility	what is shown	isolation + `visibility-grants`

Permissions through group membership

Actions go through the Policy Engine, and the policies come from your group memberships. Your permissions are the union of your groups' allow policies. Default-deny applies: without an allowing policy, the action is forbidden (403).

POST /api/v1/policy-groups/{id}/members adds a member to a group.
GET /api/v1/me/allowed-segments returns which segment values you're allowed to use for an action.

For details, see Policy Engine and the Invite your team guide.

Address roles

Access to specific addresses is defined by a role: viewer (view) or contributor (view + transfers); the canCreateAddress permission is separate. A grant is issued on an address (/shares) or a folder (/grants), to a user or a group. For details, see the Share and revoke access guide.

Visibility

Visibility is isolated by default: a regular member sees only their own addresses, operations, and balances. Permissions are applied before aggregation, so other members' data doesn't leak even into totals.

An administrator expands visibility selectively via POST /api/v1/vaults/{code}/visibility-grants, specifying who (subjectType: user|group) and whose data they see (scope):

`scope`	What the subject sees
`self`	only their own data
`group`	their group's data
`vault`	the entire Vault

Administrator role

The administrator is an oversight role: they see the entire Vault but don't initiate operations themselves (they have no operations of their own). This separates "the one who observes" from "the one who acts."

Redacting sensitive fields

Even within visible data, sensitive field values are redacted based on access: the value comes back as null, and the key is added to redactedFields. Show "hidden" rather than an empty value: this is deliberate redaction, not missing data.

How it all fits together

Who you are: authentication.
Which actions: group membership + Policy Engine (default-deny).
On which addresses: viewer / contributor roles (grants).
What's visible: isolation by default + visibility-grants.
Which fields: sensitive values are redacted based on permissions.

Common mistakes

Symptom	Cause
`403` for a new user	the user hasn't been added to any group (default-deny)
other members' data is missing even in totals	this is by design: permissions are applied before aggregation
`null` in a field treated as "empty"	it's redaction: check `redactedFields` and show "hidden"
an admin can't send a transfer	the admin is an oversight role with no operations of their own
a `viewer` tries to make a transfer	transfers require the `contributor` role

Next steps

Authentication in depth

Who you are: sessions, Bearer, and cookies.

Policy Engine

What you can do: policies, groups, and default-deny.

Share and revoke access

Address and folder roles, access auditing.

Counterparties and context

Context and data visibility.

Was this page helpful?