# Team vault

> Keep a team's API keys, tokens and passwords in end-to-end encrypted vault folders that only the people you add can open, and use them in requests as vault references.

Source: https://docs.subcloak.com/cloak-proxy/team/vault/

Added in Cloak Proxy 0.7.0.

{/* L9 draft. Sources: PLAN 7.4, 7.1 (secrets never sync), 7.14 (reveal policy), 7.15 (vault.read), 10 (Vault window); T6, T7. Re-check labels against L8. */}

The team vault holds secrets your team shares: API keys, tokens, passwords, private keys and notes. Secrets are kept in **folders**, and each folder lists exactly who can open it. Requests use a secret by name, and the value is filled in on the Mac when the request is sent, so it never sits in a workspace.

## How access works

{/* PLAN 7.4; T6 (vault always restricted), T7 */}

- Every vault folder is a [restricted space](https://docs.subcloak.com/cloak-proxy/team/spaces-and-roles/#open-and-restricted-spaces) with its own key. A Mac can open a folder only if its owner is listed in the folder, and only after a signed grant from a Mac that already has the key.
- Admins can't open a folder they aren't listed in, or change who can. Only a folder's managers change who's listed in it and their roles; an admin listed as a viewer or editor can't. To cut someone off from a folder, ask one of its managers, or remove them from the team. {/* T6.1 v1, T20 item 23; v1.3 M1: only managers write the ACL */}
- The [Team Recovery Kit](https://docs.subcloak.com/cloak-proxy/team/team-keys/#the-team-recovery-kit) can open every folder.
- Subcloak's server can't read any folder, its items or their names. Even with automatic approval after SSO on, a Mac it admits can't open a folder until its person compares a code between their two Macs.

## Create a folder and add people

1. Open **Vault** in the sidebar under **Team: Acme**, or from the **Team** menu.

2. Create a folder, for example **Staging**. You're its first **Manager**.

3. Open the folder's **Access** sheet and add people, with a role: **Viewer** can use and read the items, **Editor** can also change them, **Manager** can also change who has access.

4. Add items: a **Name**, a kind (**Token**, **Password**, **Key** or **Note**), the value, optional notes and, if you like, the hosts it may be sent to.

When you add someone, Macs that hold the folder's key grant it to the new person's Macs automatically. When you remove someone, the folder gets a new key, granted to whoever remains. {/* PLAN 7.4 access changes; T7.3, T7.4 */}

## Use a secret in a request

{/* PLAN 7.4 use */}

Write `{{vault:team/NAME}}` (or `{{vault:team/FOLDER/NAME}}`) in a request, header, body or auth field. A reference held in an environment, collection or data variable isn't filled in: write it in the request itself. Cloak Proxy fills in the value on your Mac when the request is sent, including from the runner, flows, monitors on your Mac and `cloakctl collection run`, and only to the hosts set on the item: for an AI request its base URL, for a SQL request its database server (a SQLite, CSV or JSON file gets no team values), and for an OAuth 2.0 token refresh the token URL. For a SQL, AI or MCP request, team values go only where they authenticate: a SQL request takes them in its connection (address and password), not in the query; an AI request only as its API key, not in a prompt, and not in the MCP servers it calls; an MCP request in its server's URL and headers, not in tool arguments. A request that names one anywhere else isn't sent. It isn't filled in for Cloak Proxy's own MCP tools and AI assistants, in scripts, or in Copy as cURL and code export, which keep the reference. If a response echoes a value back, Cloak Proxy tries to show its reference instead in scripts, the result, history and the cookie jar: it recognises the value as written and in some common encodings (JSON escaping, URL encoding, base64, hex), but not every form a server can produce, and a value shorter than 4 characters not at all. So any server that receives a team value can be made to send it back in a form Cloak Proxy doesn't recognise by whoever writes the request (an HTTP request to a database's HTTP API, for example). The protection is who can change the request: a request that changed on another Mac gets no team values until you've reviewed it, and each item goes only to the hosts set on it, so set them to servers you trust with it. A SQL request that uses a team value gives no result rows to scripts, its own or one that runs it with `pm.execution.runRequest`. A request that changed on another Mac and isn't reviewed yet, or a workspace you don't trust, gets no vault values. If a value can't be filled in, the request isn't sent and Cloak Proxy says why. {/* MacA v1.5.9-mac (a), R4D-H1 */}

If two folders you can open both have an item called `NAME`, write `{{vault:team/FOLDER/NAME}}`. Live sessions (WebSocket and the other realtime editors) don't fill in team vault values. It works like the [Keychain vault](https://docs.subcloak.com/cloak-proxy/api-client/variables-and-environments/#keep-secrets-in-the-vault)'s `{{vault:name}}`.

| Protection | Enforced by |
|---|---|
| Only people listed in the folder can read its values | The keys (cryptographic) |
| A value is sent only to the hosts set on the item, if any | Cloak Proxy on each Mac |
| **Reveal** and **Copy** need Touch ID or your login password | Cloak Proxy on each Mac |
| On each Mac, values are stored encrypted, with the key in your Keychain, never in plain text on disk | Cloak Proxy on each Mac |
| The policy **Vault: reveal and copy** can block revealing and copying | Cloak Proxy on each Mac |
| Cloak Proxy's own MCP tools and AI assistants never get team vault values filled in (a shared MCP server you install gets the ones its approved version names, through `cloakctl mcp-exec`) | Cloak Proxy on each Mac |

Secret environment values never sync in a team. {/* PLAN 7.1. "Move to vault" isn't built (R4D-H1): don't mention it. */}

## When someone leaves a folder

{/* PLAN 7.4, 12.2 removed member */}

Removing a person from a folder, or from the team, changes the folder's key, so they can't open anything written to it afterwards. They may still have the values they could read before. The Mac that changes the key says so, naming the person and the items they could read until then, and asks you to change those secrets at their source. Rotate each item in the folder with the service that issued it. {/* R4D-M2 */}

## What the audit log shows

{/* PLAN 7.4 audit, 7.15 */}

The [audit log](https://docs.subcloak.com/cloak-proxy/team/audit-log/) records `vault.read` when a Mac downloads a folder's items, at most once per Mac, folder and hour (past 2,000 such entries for one member in a day, once per member, folder and day: every folder read is still recorded). It means "downloaded", not "used": because the vault is end-to-end encrypted, Subcloak can't see when a value is used, or which one. It never records item names or values.

## History

Every change to an item is kept for 90 days. See [Version history](https://docs.subcloak.com/cloak-proxy/team/version-history/).

## Related

  - [Spaces, roles and permissions](https://docs.subcloak.com/cloak-proxy/team/spaces-and-roles/): Restricted spaces and space roles.
  - [Shared agent setups](https://docs.subcloak.com/cloak-proxy/team/agent-setups/): MCP servers that use vault references, never keys.
  - [Monitors](https://docs.subcloak.com/cloak-proxy/team/monitors/): Sending a secret to a server-side monitor, and what that means.
  - [Remove people and leave a team](https://docs.subcloak.com/cloak-proxy/team/leaving-and-removal/): Key changes after a removal.