The @cai.com vault - site credentials, agent retrieval, and the user-confirmation pattern

The vault is the part of CAI that removes "please paste your password" from the agent conversation. This post walks through the vault API in detail: how the user saves a credential, how the agent retrieves it, and the user-confirmation pattern that gates every retrieval.

The vault in one sentence

A user-scoped credential store for site logins and passwords. The user saves a credential for example.com. The agent the user builds retrieves it, with the user's explicit confirmation, when the agent needs to log in to example.com on the user's behalf. The vault is encrypted at rest and indexed by site.

What the vault is NOT

The vault is not for the agent's API key. The agent's CAI_API_KEY is a separate secret, used by the agent to call CAI's API. Storing it in the vault is a circular dependency. The vault is for the third-party sites the agent logs in to on the user's behalf.

The vault is not for arbitrary user secrets (API keys for other services, SSH keys, etc.). The vault is scoped to site logins: (site, username, password). For other secret types, use the appropriate secret manager.

Saving a credential (user action)

The user saves a credential from the account dashboard, or the agent the user builds can prompt the user to save a credential after a successful login. The save call:

curl -X POST https://api.cai.com/functions/v1/user-site-credentials \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_url": "https://example.com",
    "username": "alice",
    "password": "..."
  }'

The credential is encrypted at rest. The user can revoke any vault entry from the account dashboard.

Retrieving a credential (agent action, behind user confirmation)

When the agent the user builds needs to log in to example.com, the agent calls vault_get_site_credential which hits GET /user-site-credentials?origin_host=example.com. The retrieval is gated on a user-confirmation hosted-action page. The user sees the site and the username, and taps once to approve.

curl -X GET "https://api.cai.com/functions/v1/user-site-credentials?origin_host=example.com" \
  -H "Authorization: Bearer ***"

The response includes a hosted-action URL for the user to confirm. After the user taps, the agent receives the credential.

The user-confirmation pattern is the security model. Without the user's tap, the agent does not get the credential. This is the same pattern as the wallet's wallet-custodial-transfer. The agent's API key authorizes the call to the API, but the user's consent on the hosted-action page authorizes the use of the resource.

Why this design

The pattern removes three failure modes that have plagued agent tools since 2024:

1. The "paste your password" failure mode. The user pastes a password into the agent conversation, the password ends up in the model's context window, the model may log it, and the user has to rotate the password. The vault removes this entirely.
2. The "agent has the key" failure mode. The agent holds the user's password, the agent's storage is compromised, and the user's password leaks. The vault plus user-confirmation pattern means the agent never holds the password in long-term storage.
3. The "agent logs in silently" failure mode. The agent logs in to a site the user did not expect, and the user has no visibility into the action. The user-confirmation hosted-action page makes every retrieval a visible, consensual action.

The vault is the practical implementation of "the user is in the loop on every privileged action."

What the agent can do with a retrieved credential

The agent receives the credential as (site, username, password). The agent can use it to log in to the site via the site's own login flow. The agent should not log the credential, should not include it in any error message, and should not pass it to any third-party service.

After the agent is done with the action, the credential is not "checked back in." The vault holds the only copy. The next retrieval is a fresh call.

The vault and the wallet, side by side

	Wallet	Vault
Stores	Stablecoin balances on six chains	Site logins and passwords
Custody	CAI holds the private key	CAI holds the encrypted credential
User-confirmation	wallet-custodial-transfer returns a hosted-action URL	GET /user-site-credentials returns a hosted-action URL
Authorization	Agent's CAI_API_KEY with pay scope	Agent's CAI_API_KEY with appropriate scope
Receipt	GET /transfer-status returns the on-chain tx hash	The agent's logged-in session on the target site

The two surfaces are designed the same way. The user-confirmation pattern is the same pattern. The receipt is the same shape.

Safety first

The vault removes the need to paste passwords into chat, but we built this with practical safety in mind:

• Agents operate within a $200/day auto-limit while we complete our security audit.
• New recipients and new devices always require user confirmation.
• Think of it like cash in your pocket: perfect for daily spending and site logins, not for storing your life savings.
• A vault product with multi-sig and time-locks is coming for larger credential sets.

The vault API is in cai.com/skill.md. The user-facing flow is in the account dashboard. Apply at cai.com/app to get a vault.

---

If you used the vault and the agent retrieved the wrong credential, or the user-confirmation flow did not surface

Comment below with:

1. What you ran - the install command, the request, the MCP host config. Copy the actual command or request.
2. What you expected - one sentence.
3. What you got - the error message, the empty response, the unexpected behavior. Paste it verbatim.
4. Your environment - OS, Node version, the MCP host (OpenClaw / Hermes / Codex / Cursor / other), the CAI account tier if relevant.

Every comment on this article gets read. Bug reports will be replied to within 24 hours. Friction points shape what we document next.

Documentation: cai.com/skill.md · cai.com/developers.html · cai.com/app to sign up.