使用保管庫進行驗證

「Vaults」（保管庫）和「credentials」（憑證）是驗證原語，讓您可以一次性註冊第三方服務的憑證，並在建立工作階段時透過 ID 引用它們。這意味著您不需要執行自己的密鑰儲存庫、在每次呼叫時傳輸權杖，或無法追蹤代理程式代表哪位終端使用者執行操作。

保管庫引用是每個工作階段的參數，因此您可以在 agent 資源粒度管理您的產品，並在 session 資源粒度管理您的使用者。



建立保管庫

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

VAULT_ID=$(ant beta:vaults create \
  --display-name "Alice" \
  --metadata '{external_user_id: usr_abc123}' \
  --transform id --raw-output)
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 憑證（mcp_oauth、static_bearer）：每個憑證以 mcp_server_url 作為索引鍵。當代理程式在工作階段執行時連接到該 URL 的伺服器時，權杖會自動注入。
• 環境變數（environment_variable）：每個憑證以 secret_name（環境變數名稱）作為索引鍵，並以不透明的預留位置形式儲存在沙箱中。當代理程式發起對外請求時，不透明的預留位置會在出口處被替換為真實的密鑰。代理程式永遠不會看到密鑰值。對於任何透過環境變數進行驗證的服務（例如 CLI、SDK 或直接 API 呼叫），請使用此類型。

您提供的實際憑證值（token、access_token、refresh_token、client_secret、secret_value）會被視為敏感的唯寫欄位，且永遠不會在 API 回應中傳回。

憑證會依提供的內容儲存，且在工作階段執行時才會進行驗證。無效的憑證會在工作階段期間以驗證錯誤或下游錯誤的形式浮現，該錯誤會被發出，但不會阻止工作階段繼續進行。

限制條件：

• 每個保管庫的索引鍵必須唯一。 mcp_server_url（MCP 憑證）和 secret_name（環境變數憑證）在保管庫的有效憑證中必須是唯一的。建立重複項目會傳回 409。
• 索引鍵不可變更。 若要變更 mcp_server_url 或 secret_name，請封存該憑證並建立新的憑證。
• 每個保管庫最多 20 個憑證。



在建立工作階段時引用保管庫

建立工作階段時傳遞 vault_ids：

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --vault-id "$VAULT_ID" \
  --title "Alice's Slack digest" \
  --transform id --raw-output)

執行時行為：

• 當沒有 MCP 憑證透過 mcp_server_url 匹配時，會嘗試未經驗證的連線，如果伺服器需要驗證則會發生錯誤。
• 當多個保管庫包含匹配的憑證時，第一個有匹配項目的保管庫優先。
• 在多代理程式工作階段中，保管庫憑證適用於每個執行緒。自身定義中宣告了匹配 MCP 伺服器的代理程式會使用這些憑證進行驗證。請參閱將代理程式連接到 MCP 伺服器。



輪替憑證

密鑰值、display_name 以及（環境變數憑證上的）injection_location 可以更新。injection_location 的更新會依欄位合併，如新增憑證的「環境變數」分頁所述。對於執行中的工作階段，injection_location 更新的傳播方式與密鑰輪替相同：工作階段的憑證會在不重新啟動的情況下重新解析，如憑證生命週期所述，且更新後的位置會套用至該工作階段後續的對外請求。結構性欄位（mcp_server_url、secret_name、token_endpoint、client_id）在建立後即鎖定。若要變更它們，請封存該憑證並建立新的憑證。

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



憑證生命週期

憑證會定期重新解析，無論是在工作階段期間還是在保管庫生命週期期間。這確保憑證的輪替、封存或刪除能傳播到執行中的工作階段，而無需重新啟動。

若要在憑證被封存、刪除或重新整理失敗時收到通知，您可以訂閱與這些生命週期變更相關的保管庫和憑證 webhooks。

對於 mcp_oauth 憑證，重新解析也會在存取權杖過期時重新整理它。如果重新整理失敗，會發出 vault_credential.refresh_failed 事件。



診斷 OAuth 重新整理失敗

若要診斷重新整理失敗的原因，請呼叫 POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate（或在 SDK 中呼叫 client.beta.vaults.credentials.mcp_oauth_validate(...)）。這讓您可以決定如何處理失敗；正確的處理方式取決於錯誤類型。

頂層的 status 告訴您接下來該做什麼：

• valid：權杖有效；無需採取任何動作。
• invalid：授權已失效，或 OAuth 伺服器以 4xx 拒絕了重新整理。提示終端使用者重新授權。
• unknown：暫時性錯誤（5xx、429 或網路故障）。等待後重試。

ant beta:vaults:credentials mcp-oauth-validate \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" \
  --transform status --raw-output  # "valid", "invalid", or "unknown"

回應是一個 vault_credential_validation 物件。mcp_probe 包含失敗的 MCP 交握步驟；refresh 包含嘗試重新整理的結果。

{
  "type": "vault_credential_validation",
  "credential_id": "vcrd_01ABC...",
  "vault_id": "vlt_01XYZ...",
  "validated_at": "2026-04-29T17:12:00Z",
  "has_refresh_token": false,
  "status": "invalid",
  "mcp_probe": {
    "method": "initialize",
    "http_response": {
      "status_code": 401,
      "content_type": "application/json",
      "body": "{\"error\":\"invalid_token\"}",
      "body_truncated": false
    }
  },
  "refresh": {
    "status": "no_refresh_token",
    "http_response": null
  }
}



其他操作

• 列出保管庫或憑證： 分頁顯示，最新的在前。預設排除已封存的記錄（傳遞 include_archived=true 以包含它們）。
• 封存保管庫： POST /v1/vaults/{id}/archive。會連帶封存所有憑證。密鑰會被清除；記錄會保留以供稽核。未來引用此保管庫的工作階段會失敗；執行中的工作階段會繼續。
• 封存憑證： POST /v1/vaults/{id}/credentials/{cred_id}/archive。清除密鑰酬載；憑證索引鍵（mcp_server_url 或 secret_name）仍然可見，並釋放供替代憑證使用。
• 刪除保管庫或憑證： 硬刪除。記錄不會保留。如果您需要稽核軌跡，請使用封存。