> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentity.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Vault

> Each agent gets an isolated encrypted secret store where you can save and retrieve sensitive values like card details and API tokens.

The vault is an encrypted per-agent secret store. Every agent has its own isolated vault namespace — secrets written for one agent are never accessible from another.

## How secrets are stored

Secrets are key-value pairs where both the key and the value are strings. Values are encrypted before being written to Infisical. Agentity stores only ciphertext and never has access to your plaintext values at rest.

<Note>
  All vault secrets are encrypted at rest. Agentity stores only encrypted ciphertext.
</Note>

## Initialization

You must initialize a vault before you can write secrets to it. Call `initialize_vault` with the agent's `agentId` before calling `save_secret_to_vault`. Attempting to write a secret to an uninitialized vault returns an error.

<Tip>
  Initialize the vault before creating the identity so you can immediately store card details after provisioning.
</Tip>

## Available operations

All vault operations are available as MCP tools:

| Tool                    | Description                                                                                              |
| ----------------------- | -------------------------------------------------------------------------------------------------------- |
| `initialize_vault`      | Creates an isolated vault namespace for the agent. Must be called once before any other vault operation. |
| `save_secret_to_vault`  | Writes an encrypted key-value secret to the agent's vault.                                               |
| `get_secret_from_vault` | Reads and decrypts a secret from the agent's vault by key.                                               |

Every vault tool call requires an `agentId` and an `intent` object. The intent is recorded in your audit log.

## Common use cases

* **Virtual card details** — Store `pan`, `cvv`, `exp_year`, and `exp_month` immediately after calling `create_agent_identity`.
* **API credentials** — Save third-party API tokens the agent needs to operate.
* **Session tokens** — Persist short-lived tokens between agent runs.
* **Any sensitive string** — Anything you would not want stored in plaintext.

## Example: saving a secret

```json theme={null}
{
  "agentId": "agent-42",
  "secretKey": "VIRTUAL_CARD_PAN",
  "secretValue": "4111111111111111",
  "intent": {
    "message": "Storing virtual card PAN after identity provisioning",
    "subject": "VAULT",
    "action": "CREATE"
  }
}
```

## Example: reading a secret

```json theme={null}
{
  "agentId": "agent-42",
  "secretKey": "VIRTUAL_CARD_PAN",
  "intent": {
    "message": "Retrieving virtual card PAN to complete a purchase",
    "subject": "VAULT",
    "action": "READ"
  }
}
```