使用保險庫進行驗證

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

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

建立保險庫

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

VAULT_ID=$(ant beta:vaults create \
  --display-name "Alice" \
  --metadata '{external_user_id: usr_abc123}' \
  --transform id --raw-output)

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

{
  "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 與參照保險庫上的有效憑證進行比對，並注入令牌。

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

限制：

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

輪換憑證

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

ant beta:vaults:credentials update \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" <<'EOF'
auth:
  type: mcp_oauth
  access_token: xoxp-new-...
  expires_at: "2099-12-31T23:59:59Z"
  refresh:
    refresh_token: xoxe-1-new-...
EOF

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

建立工作階段時傳入 vault_ids：

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
    title="Alice's Slack digest",
)

執行時行為：

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

其他操作

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