---
title: Vaults and credentials
description: Where a session's tool credentials live. The broker uses them at call time; the engine and the model never see them.
sidebar:
  order: 5
---

An agent that can only talk is not much use. The moment it reaches a real system it needs a real credential — and the one place that credential must never end up is in the model's context.

A **vault** is a workspace-scoped store of credentials. A session names the vaults it may draw from; when a tool call goes out, the **broker** matches it against those vaults, attaches the credential, and makes the call. The engine is handed the broker's URL and a run token, never a secret.

## Creating a vault

```bash
subako vault create --display-name "Acme production"
subako vault list
```

`--metadata` takes a JSON file of arbitrary data to store alongside the vault — a tenant id, a region, whatever your own routing needs.

## Adding a credential

The payload is read from stdin as JSON, so secrets stay out of your shell history and out of the process list.

```bash
subako vault add-credential <vault-id> \
  --protocol mcp \
  --target https://mcp.acme.example/sse \
  --display-name "Acme MCP" < credential.json
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `protocol` | `string` | - | What the credential authenticates. `subako vault protocols` lists what this server accepts — the server owns the vocabulary, so one added there works from the CLI unchanged. |
| `target` | `string` | - | What the broker matches a tool call against. For `mcp`, the server's exact URL. |

The protocol is stated, never defaulted. It decides how `--target` is read, and a vault holds each target once per protocol at a time: adding a second live credential for a target it already holds is refused with `credential target already exists`.

The payload arrives on stdin as JSON, and names its `auth_scheme` — which says what the rest of its fields are:

```json credential.json
{ "auth_scheme": "static_bearer", "token": "..." }
```

`oauth` is the other scheme; it carries `access_token`, and optionally `expires_at` and a `refresh` block.

## Listing and deleting

```bash
subako vault credentials <vault-id>
```

Credentials are listed, never their payloads. There is no read-back: a secret goes in and only the broker sees it again.

```bash
subako vault delete-credential <vault-id> <credential-id>
subako vault delete <vault-id>
```

Both ask you to type the id back; `--yes` skips that for scripts. Deleting a credential purges its secret and frees the target it claimed, so the same target can be given a new credential — that is how you rotate one. Deleting a vault takes every credential in it and purges all of their secrets.

## Why the session names the vaults

Vaults are named per session, not baked into an agent version. One published version can therefore serve one customer against their production vault and another against a sandbox, with nothing republished in between — the version says what the agent may do, and the session says whose credentials it does it with.