# Vault

A **vault** is Ren's encrypted credential store. API keys, OAuth tokens, environment variables, and service passwords live here so [agents](/docs/deep-dives/concepts/agents/agents/) and [MCPs](/docs/deep-dives/concepts/agents/mcps/) can authenticate against external services at runtime, without secrets ever appearing in a prompt, an agent definition, or session history.

The key idea: an MCP or skill **declares** a credential slot ("I need a bearer token called `api-key`"); the vault **holds** the actual value. At runtime Ren fills the slot from the vault. The same MCP can use different credentials in different projects just by attaching different vaults.

## Credential types

A vault holds up to 20 credentials, each typed so Ren knows how to inject it:

| Type       | When to use                                                                                                                                         |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bearer** | A static API token sent in the `Authorization: Bearer` header. The most common type.                                                                |
| **OAuth**  | Delegated auth flows (e.g. GitHub, Google Workspace). Ren stores the access token and refreshes it automatically when a refresh token is available. |
| **Env**    | A raw environment variable, for config values or keys that don't fit the bearer pattern.                                                            |
| **Basic**  | HTTP Basic auth (username + password), for services that still require it.                                                                          |

## Encryption and archival

Each vault is encrypted with its own key, so compromising one vault doesn't expose another. Ren handles encryption and decryption for you.

Archiving a credential is permanent: the slot remains (so references don't break) but the secret value is gone and must be re-created if you need it again.

## Attaching vaults

Vaults attach to [pods](/docs/deep-dives/concepts/compute/pods/) and [projects](/docs/deep-dives/concepts/compute/projects/) with a **priority**. When the same credential exists in more than one vault, the higher-priority vault wins. This lets you layer secrets: an org vault provides defaults, and a team vault overrides just the keys that differ.

Every pod gets a **default vault** at creation, so agents always have somewhere to store and retrieve secrets.

## How requirements are checked

When a session starts, Ren walks the project's agents (and the skills and MCPs each one uses) and collects every credential they declare. For each one it checks whether a matching value exists in an attached vault. Anything missing is flagged before the agent runs, so you can see which agents would break and supply the secret up front.

## OAuth

For services that need user-delegated access (GitHub, Google Workspace), Ren runs the full OAuth flow and stores the resulting token in the vault. If the access token expires and a refresh token exists, Ren refreshes it automatically. You only re-authorize if the refresh token is revoked.

## Using vaults from the CLI

```bash
ren vaults list              # view vaults in your workspace
ren vaults create --name "X" # create a vault
```

## Where to go next

- [MCPs](/docs/deep-dives/concepts/agents/mcps/): how MCPs declare credential slots agents fill from a vault.
- [Pods](/docs/deep-dives/concepts/compute/pods/): what vaults attach to, and how priority works.
- [Memory stores](/docs/deep-dives/concepts/stores/memory-stores/): persistent state that isn't secret.