# Overview

What vault secrets are and how they're injected into agent environments.



A **vault secret** is a single encrypted key/value pair stored inside a [vault](/api/vaults/overview). Each secret has an `env_key` (the environment variable name), a `value` (encrypted at rest), and an optional list of `allowed_domains` that restricts where the value can be used.

When an agent has a vault attached, every secret in that vault is injected into the agent's container environment. Domain restrictions are enforced at the network proxy level — the secret is only revealed to outbound requests targeting one of its `allowed_domains`.

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

1. Create the parent vault first (see [Vaults](/api/vaults/overview)).
2. Add secrets with `POST /vaults/{vault_id}/secrets`, passing `env_key`, `value`, and optionally `allowed_domains` (for example `["*.stripe.com"]`).
3. Attach the vault to an agent. The secret becomes available inside the agent's container as the named env var.
4. Update or rotate the secret's value any time with `PATCH /vaults/{vault_id}/secrets/{secret_id}` — every agent using the vault picks up the new value automatically (no redeploy required, refresh runs on a short interval).

For security reasons, the `value` field is **never returned** by `GET` endpoints. Only the metadata (`env_key`, `allowed_domains`, timestamps) comes back. Treat the moment of creation as your only chance to capture the plaintext.

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

* **Hand production credentials to agents without leaking them.** Stripe keys, GitHub tokens, database passwords — encrypted at rest, never returned by `GET`.
* **Cap the blast radius of a leak.** Lock a secret to specific destinations with `allowed_domains` (for example `["*.stripe.com"]`) so it can't be exfiltrated to an arbitrary URL.

For non-sensitive configuration, use [env vars](/api/env-vars/overview) instead — those are plaintext and per-agent.