Workspace Secrets Vault

Workspace Secrets (vault_secret)

The vault_secret tool provides a first-class primitive for storing API keys, tokens, PEM files, and other sensitive values — separate from the file namespace. Secrets are encrypted at rest (AES-256-GCM, per-workspace key) and never appear in file listings, search results, browser URLs, diffs, or audit log plaintext.

Note: The vault is only accessible programmatically via the vault_secret MCP tool (used by AI agents), not through the web UI.

Actions

Action	Description
`put`	Store or update a secret. Use `mode: "create"` to fail if exists, or `"upsert"` (default).
`get`	Retrieve a secret. Returns masked value by default. Set `reveal: true` and provide `purpose` for plaintext.
`list`	List all accessible secrets (metadata only, no values).
`rotate`	Update the value of an existing secret, incrementing its version.
`delete`	Permanently delete a secret (not soft-delete — old values are irrecoverable).

Example: Store an OpenAI key

vault_secret({
  "action": "put",
  "name": "openai/default_api_key",
  "value": "sk-proj-...",
  "mode": "create",
  "allowedAgentIds": ["agent_research", "agent_builder"],
  "description": "Default OpenAI API key for workspace agents"
})

Example: Retrieve it later

vault_secret({
  "action": "get",
  "name": "openai/default_api_key",
  "reveal": true,
  "purpose": "Call OpenAI API for summarization task"
})

Security properties

Encrypted at rest — per-workspace AES-256-GCM key derived from workspace identity
Not part of file namespace — never appears in list_files, search_files, or browser_url
Plaintext never in audit logs — audit entries record only metadata and SHA-256 fingerprint
Access control — optional allowedAgentIds restricts which agents can read the secret
Expiration — optional expiresAt (RFC 3339) makes the secret inaccessible after that time
Reveal requires purpose — get with reveal: true requires a purpose string recorded in the audit trail
⚠️ Reveal exposes plaintext to LLM context — when reveal: true is used, the decrypted secret value is returned in the MCP tool response, which means it enters the agent’s context window. This is by design (agents need the secret to make API calls), but be aware that the value may appear in LLM provider logs depending on your provider’s data retention policy. Use allowedAgentIds to limit which agents can request reveal.
No version history — old secret values are overwritten, not retained (unlike files)
64 KiB size cap — designed for keys and tokens, not arbitrary blobs

Parameters

Parameter	Type	Required	Notes
`action`	`"put" \| "get" \| "list" \| "rotate" \| "delete"`	yes	Operation to perform
`name`	string	except `list`	Logical secret name, e.g. `openai/default_api_key`
`value`	string	for `put`/`rotate`	Secret value
`encoding`	`"utf-8" \| "base64"`	no	Default `utf-8`; use `base64` for binary blobs
`mode`	`"create" \| "upsert"`	no	For `put`; default `upsert`
`allowedAgentIds`	string[]	no	If omitted, all agents can access
`description`	string	no	Human-readable note
`tags`	string[]	no	Optional labels
`expiresAt`	string (RFC 3339)	no	Auto-expire
`reveal`	boolean	no	For `get`; default `false`
`purpose`	string	when `reveal=true`	Required audit reason for plaintext retrieval

​Workspace Secrets (vault_secret)

​Actions

​Example: Store an OpenAI key

​Example: Retrieve it later

​Security properties