Secrets vault

A Verifiable Trust Agent (VTA) derives most of its signing keys from a master seed, so it can reproduce them rather than store them. Secrets that come from somewhere else, an API token issued by a third party or a password for a legacy system, cannot be derived. The secrets vault is where a VTA keeps those, under the same context scoping and access control list (ACL) that govern everything else it holds. Retrieve credentials from the VTA vault at runtime →

What the vault stores

The vault holds third-party secrets your applications need but should not carry themselves: bearer tokens, passwords, OAuth refresh tokens, SSH keys, and similar credentials your VTA did not issue.

The distinction from the rest of a VTA is the source of the material. A signing key is derived: it comes from the master seed by a BIP-32 path, so restoring the seed reproduces it. A vault secret is given: GitHub minted the token, and nothing about your seed can reconstruct it. That difference is why the vault is a store at all, and why it needs separate treatment in backup and recovery.

How a vault entry is scoped

Every entry names the context it belongs to. A caller reaching for an entry is checked against that context with the same predicate the REST routes use, so vault access obeys the boundary that already separates one application’s keys from another’s.

The practical effect is that a context is the unit of sharing. Two services enrolled in the same context reach the same entries, and a service scoped to a different context reaches that context’s entries instead, whatever its role. Only an unrestricted (super) admin reaches every context. See Keys and contexts for how that boundary is drawn.

Which roles can read and write

Vault access is expressed as capabilities rather than as a single permission, so a service can be allowed to read a secret without being allowed to replace it:

Each role carries a ceiling of capabilities rather than an automatic grant. Admin and Initiator reach all three. Application can read and release but cannot write, which is what lets a running service consume a credential it has no authority to change. Reader can only read. Monitor has no vault access at all.

Because the role is a ceiling, an entry can hold fewer capabilities than its role permits. An AI agent registered as an Application can be granted vault-read in one context and nothing else. See Roles and access for how role and context bound each other.

How a secret reaches a service

The VTA encrypts a released vault secret to the calling DID’s own key as a DIDComm authcrypt message, so a mediator or proxy relaying the response cannot read it. Opening a released secret therefore needs a DIDComm connection.

The VTA’s guarantee ends at that boundary: only the calling DID can open the response. From there the secret lives in your service’s memory, so handle it as you would any other credential your process holds, keeping it out of logs, crash dumps, and anything written to disk.

How the vault differs from the VTA’s other stores

“Vault” is the term most often overloaded when talking about a VTA, because a VTA keeps several separate stores:

Affinidi Vault is a different product entirely: an end-user application for collecting and sharing your own data. The VTA vault is infrastructure your services call, not something a person signs in to.

How the vault is backed up

An encrypted VTA backup includes the vault, so a restored VTA comes back with its entries, along with the credentials it holds as a holder. See Back up and restore VTA state for everything a backup carries.

Related