# Secrets vault

> What the VTA vault stores, how entries are scoped to a context, which roles can read or write them, and how it differs from the VTA's other stores.

A Verifiable Trust Agent (VTA) derives its own signing keys from a master seed, so those keys never need to be stored anywhere. 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 →](/products/affinidi-elements/vta/vta-management/vault-deliver-secrets.md)

## 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](/products/affinidi-elements/vta/concepts/keys-and-contexts.md), 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; a service in a different context cannot see them at all, whatever its role. See [Keys and contexts](/products/affinidi-elements/vta/concepts/keys-and-contexts.md#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:

| Capability | What it gates |
| vault-read | Reading stored credentials and secrets. |
| vault-write | Storing a secret, and changing one that already exists. |
| fill-release | Releasing a stored value into an authorised flow. |

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](/products/affinidi-elements/vta/concepts/roles-and-access.md) for how role and context bound each other.

## How a secret reaches a service

A service never receives a vault secret as plain text on the wire. The VTA encrypts the released value to the calling DID’s own key using [sealed transfer](/products/affinidi-elements/vta/concepts/sealed-transfer.md), the same mechanism that delivers credentials during provisioning, so a mediator or proxy relaying the response cannot read it.

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:

| Store | What it holds |
| Vault | Third-party secrets the VTA holds on your behalf, such as an API token. |
| Issued credentials | Verifiable credentials this VTA minted and can revoke. It issued them; it did not receive them. |
| Agent memory | Per-context key/value working state for an AI agent. See [Give your AI agent persistent memory](/products/affinidi-elements/vta/integration-guides/agent-memory.md). |
| Derived keys | Signing and key-agreement keys derived from the master seed, never stored as secrets in their own right. |

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.

## What the vault does not cover

Vault entries are excluded from a VTA backup by design, so a restored VTA comes back without them. Keep a separate copy of any secret your services depend on, and plan to re-store entries after a restore. See [Back up and restore VTA state](/products/affinidi-elements/vta/vta-management/backup-and-restore.md#known-gaps) for the full list of what a backup leaves behind.

## Related

  [Retrieve credentials from the VTA vault at runtime](/products/affinidi-elements/vta/vta-management/vault-deliver-secrets.md)

  [Sealed transfer](/products/affinidi-elements/vta/concepts/sealed-transfer.md)

  [Roles and access](/products/affinidi-elements/vta/concepts/roles-and-access.md)

  [Glossary](/products/affinidi-elements/vta/get-started/glossary.md): the terms used across these pages and in pnm output.