Roles and access
A VTA holds signing keys and secrets for every application you register with it. If every DID that authenticates to it had the same level of access, a single leaked credential, from any one of those applications, would be enough to reach every key and every secret the VTA holds. Roles limit what a leaked credential can reach to what its role allows. Every DID in the VTA’s access control list (ACL) is assigned exactly one role, and that role sets the ceiling on what the DID can do, apart from one capability that only a super admin can grant to an entry by name.
Least privilege by design
What an attacker can do with a leaked credential should match what that credential actually needs to do, not what the VTA is capable of doing:
- A backend service that only signs payloads has no legitimate reason to also mint new keys or rewrite the ACL.
- A monitoring dashboard has no legitimate reason to read key material at all.
The VTA enforces this by gating each operation on the caller’s role and, for finer control, on named capabilities, and by assigning each DID the role that matches its job rather than admin-equivalent access.
Roles
Every DID in the VTA access control list is assigned one of five roles, from most to least privileged. This role model is based on the Trust Over IP Foundation’s Verifiable Trust Infrastructure (VTI) specification’s role registry.
| Role | What it can do |
|---|---|
| Admin | Manages keys and ACL entries, and creates sub-contexts, within its allowed contexts. An Admin with an empty allowed_contexts list has unrestricted access across the entire VTA, including config changes and backup. The CLI displays this case as “super admin.” |
| Initiator | Sign data, read and write the vault, and grant or revoke non-admin ACL entries, within their allowed contexts. Can create did:webvh DIDs, which mints their keys. Creating standalone keys, promoting anyone to Admin, and changing an existing Admin entry stay with Admins. |
| Application | Sign data and Trust Tasks, read keys and contexts, read and release vault secrets, query stored credentials, perform proxy-login, read and write agent memory, and use room capabilities, within their allowed contexts. Writing to the vault and managing ACL entries need the Initiator or Admin role, and creating keys needs Admin. |
| Reader | Read-only access to list keys, contexts, and DIDs, and to read the vault and agent memory, within their allowed contexts. |
| Monitor | Infrastructure-only: metrics and health endpoints. No access to keys, contexts, DIDs, or the vault at all. |
Vault access is finer-grained than the table suggests: reading, writing, and releasing a secret are separate capabilities, and an entry can hold fewer than its role allows. See Secrets vault.
This is why Sign application payloads without exposing your keys provisions its credential with --role application rather than --role admin. A credential at that role can call the signing endpoint, but not mint keys, change the ACL, or issue credentials to new identities. Those bounds hold even if the credential leaks, so an attacker gains what the Application role allows in that context, such as signing and releasing vault secrets, rather than control of the VTA.
Role and context together
Role sets what a DID can do. Context scoping sets where. A DID’s ACL entry carries an allowed_contexts list alongside its role, and every check applies both: an Initiator scoped to one context can grant or revoke non-admin ACL entries in that context, and nowhere else. See Contexts for how context isolation works across a VTA.
An empty allowed_contexts list means different things depending on role:
- Admin: every context. This is the unrestricted “super admin” case.
- Every other role: no context at all. The entry exists but acts in no context until you add one.
This asymmetry is deliberate. Only Admin is trusted to act without a context restriction.
This mirrors the VTI specification’s distinction between super-administrators and context administrators: an unrestricted entry acts everywhere, and a scoped entry acts only within the contexts it names.
The restriction lives on the admin entry, not on the VTA itself. The same three contexts exist for everyone; what differs is which of them a given admin entry can see:
Related
Glad to hear it! Please tell us how we can improve more.
Sorry to hear that. Please tell us how we can improve.
Thank you for sharing your feedback so we can improve your experience.