使用保險庫進行驗證

保險庫和憑證是驗證基本元件，讓您可以一次性為第三方服務註冊憑證，並在建立工作階段時透過 ID 加以參照。這意味著您無需自行運行密鑰儲存庫、在每次呼叫時傳輸令牌，或追蹤代理程式代表哪位終端使用者執行操作。

保險庫參照是每個工作階段的參數，因此您可以在代理程式層級管理您的產品，並在工作階段層級管理您的使用者。

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。SDK 會自動設定 beta 標頭。

建立保險庫

保險庫和憑證的範圍限定於工作區，這意味著任何擁有 API 金鑰存取權限的人都可以使用它們來授權代理程式完成任務。若要撤銷存取權限，請刪除保險庫或憑證。

保險庫是與終端使用者相關聯的 credentials 集合。為其提供一個 display_name，並可選擇性地使用 metadata 標記，以便將其對應回您自己的使用者記錄。

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..."

回應為完整的保險庫記錄：

{
  "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
}

新增憑證

每個憑證綁定到單一 mcp_server_url。當代理程式在工作階段執行時連接到 MCP 伺服器時，API 會將伺服器 URL 與參照保險庫上的有效憑證進行比對，並注入令牌。

密鑰欄位（token、access_token、refresh_token、client_secret）為唯寫。它們永遠不會在 API 回應中返回。

憑證按提供的方式儲存，在工作階段執行時才會進行驗證。錯誤的令牌會在工作階段期間以 MCP 驗證錯誤的形式出現，該錯誤會被發出但不會阻止工作階段繼續進行。

限制：

每個保險庫每個 mcp_server_url 只能有一個有效憑證。 為相同 URL 建立第二個憑證會返回 409。
mcp_server_url 不可變更。 若要指向不同的伺服器，請封存此憑證並建立新的憑證。
每個保險庫最多 20 個憑證。 這與每個代理程式的最大 MCP 伺服器數量相符。

輪換憑證

只有密鑰有效負載和少數中繼資料欄位是可變更的。mcp_server_url、token_endpoint 和 client_id 在建立後即被鎖定。

在建立工作階段時參照保險庫

建立工作階段時傳入 vault_ids：

執行時行為：

憑證在工作階段期間會定期重新解析，因此輪換或封存操作無需重新啟動即可傳播到正在執行的工作階段。
當保險庫沒有 MCP 伺服器的憑證時，連線將以未驗證的方式嘗試並產生錯誤。
當多個保險庫涵蓋同一個 MCP 伺服器時，第一個匹配的保險庫獲勝。

其他操作

列出保險庫或憑證： 分頁顯示，最新的排在最前面。預設情況下排除已封存的記錄（傳入 include_archived=true 以包含它們）。
封存保險庫： POST /v1/vaults/{id}/archive。會級聯到所有憑證。密鑰會被清除；記錄會保留以供稽核。未來參照此保險庫的工作階段將失敗；正在執行的工作階段則繼續。
封存憑證： POST /v1/vaults/{id}/credentials/{cred_id}/archive。清除密鑰有效負載；mcp_server_url 仍然可見。釋放 mcp_server_url 以供替換憑證使用。
刪除保險庫或憑證： 硬刪除。記錄不會保留。如果您需要稽核記錄，請使用封存。

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

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
)