# Overview

What vaults are and how they group secrets for agent injection.



A **vault** is a logical container for related secrets. Vaults are how you organize credentials by purpose — one vault for production database keys, another for third-party API tokens, another for staging — and attach them to agents as a single unit.

Vaults themselves hold no secret material. The actual credentials live inside as [vault secrets](/api/vault-secrets/overview). A vault is the addressable group: you create it, attach it to an agent, then add or rotate secrets inside it independently.

## How it works [#how-it-works]

1. Create a vault with `POST /vaults`, giving it a `name` and optional `description`.
2. Add secrets to it via [vault secrets](/api/vault-secrets/overview) (`POST /vaults/{vault_id}/secrets`).
3. Attach the vault to one or more agents via [agent resources](/api/agent-resources/overview) (`entity_type: "vault"`).
4. Redeploy. Every secret in the vault is now injected into the agent's container environment, scoped by each secret's `allowed_domains`.

Rotating a secret inside the vault propagates automatically — every agent the vault is attached to picks up the new value on the next refresh, no redeploy needed.

## When to use it [#when-to-use-it]

* **Hand a whole credential set to an agent in one attachment.** Group production database creds, third-party API tokens, or per-environment secrets into a single vault and attach the vault, not individual secrets.
* **Rotate in one place, propagate everywhere.** Update a value in the vault and every agent attached to it sees the new value within minutes — no redeploy.

For non-sensitive configuration (build flags, log levels), use [env vars](/api/env-vars/overview) instead — vaults are for secrets only.