Authenticate with vaults

Vaults and credentials are authentication primitives that let you register credentials for third-party services once and reference them by ID at session creation. This means you don't need to run your own secret store, transmit tokens on every call, or lose track of which end user an agent acted on behalf of.

The vault reference is a per-session parameter, so you can manage your product at the agent level and your users at the session level.

Create a vault

A vault is the collection of credentials associated with an end-user. Give it a display_name and optionally tag it with metadata so you can map it back to your own user records.

vault_id=$(curl --fail-with-body -sS https://api.anthropic.com/v1/vaults \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF' | jq -r '.id'
{
  "display_name": "Alice",
  "metadata": {"external_user_id": "usr_abc123"}
}
EOF
)
echo "$vault_id"  # "vlt_01ABC..."

The response is the full vault record:

{
  "type": "vault",
  "id": "vlt_01ABC...",
  "display_name": "Alice",
  "metadata": { "external_user_id": "usr_abc123" },
  "created_at": "2026-03-18T10:00:00Z",
  "updated_at": "2026-03-18T10:00:00Z",
  "archived_at": null
}

Add a credential

Each credential binds to a single mcp_server_url. When the agent connects to an MCP server at session runtime, the API matches the server URL against active credentials on the referenced vault and injects the token.

Credentials are stored as provided and are not validated until session runtime. A bad token surfaces as an MCP auth error during the session, which is emitted but does not block the session from continuing.

Constraints:

• One active credential per mcp_server_url per vault. Creating a second credential for the same URL returns a 409.
• mcp_server_url is immutable. To point at a different server, archive this credential and create a new one.
• Maximum 20 credentials per vault. This matches the maximum amount of MCP servers per agent.

Rotate a credential

Only the secret payload and a handful of metadata fields are mutable. mcp_server_url, token_endpoint, and client_id are locked after creation.

curl --fail-with-body -sS \
  "https://api.anthropic.com/v1/vaults/$vault_id/credentials/$credential_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF' > /dev/null
{
  "auth": {
    "type": "mcp_oauth",
    "access_token": "xoxp-new-...",
    "expires_at": "2026-05-15T00:00:00Z",
    "refresh": {"refresh_token": "xoxe-1-new-..."}
  }
}
EOF

Reference the vault at session creation

Pass vault_ids when creating a session:

session_id=$(curl --fail-with-body -sS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF | jq -r '.id'
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "vault_ids": ["$vault_id"],
  "title": "Alice's Slack digest"
}
EOF
)

Runtime behavior:

• Credentials are re-resolved periodically during the session, so a rotation or archive propagates to running sessions without a restart.
• When a vault has no credential for the MCP server, the connection is attempted unauthenticated and produces an error.
• When multiple vaults cover the the MCP server, the first vault with a match wins.

Other operations

• List vaults or credentials: Paginated, newest first. Archived records are excluded by default (pass include_archived=true to include them).
• Archive a vault: POST /v1/vaults/{id}/archive. Cascades to all credentials. Secrets are purged; records are retained for auditing. Future sessions referencing this vault fail; running sessions continue.
• Archive a credential: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Purges the secret payload; mcp_server_url remains visible. Frees the mcp_server_url for a replacement credential.
• Delete a vault or credential: Hard delete. The record is not retained. Use archive if you need an audit trail.