使用 vault 進行驗證

Vault（保管庫）與 credential（憑證）是驗證基本元件，讓您只需為第三方服務註冊一次憑證，之後在建立 session 時即可透過 ID 參照它們。這表示您不需要自行運行機密儲存庫、在每次呼叫時傳送權杖，也不會搞不清楚代理是代表哪位終端使用者執行操作。

Vault 參照是每個 session 的參數，因此您可以在 agent 資源的粒度管理您的產品，並在 session 資源的粒度管理您的使用者。

建立 vault

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

VAULT_ID=$(ant beta:vaults create --transform id --raw-output < alice.vault.yaml)
echo "$VAULT_ID"  # "vlt_01ABC..."

display_name: Alice
metadata:
  external_user_id: usr_abc123

回應為完整的 vault 記錄：

{
  "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 作為鍵。當代理在 session 執行期間連線至該 URL 的伺服器時，權杖會自動注入。
• 環境變數（environment_variable）：每個憑證以 secret_name（環境變數名稱）作為鍵，並以不透明的佔位符形式儲存在沙箱中。當代理發起對外請求時，不透明佔位符會在出口處被替換為真正的機密。代理永遠不會看到機密值。任何透過環境變數進行驗證的服務都可使用此方式，例如 CLI、SDK 或直接的 API 呼叫。

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

CREDENTIAL_ID=$(ant beta:vaults:credentials create \
  --vault-id "$VAULT_ID" \
  --display-name "Alice's Slack" \
  --transform id --raw-output <<'YAML'
auth:
  type: mcp_oauth
  mcp_server_url: https://mcp.slack.com/mcp
  access_token: xoxp-...
  expires_at: "2099-12-31T23:59:59Z"
  refresh:
    token_endpoint: https://slack.com/api/oauth.v2.access
    client_id: "1234567890.0987654321"
    scope: channels:read chat:write
    refresh_token: xoxe-1-...
    token_endpoint_auth:
      type: client_secret_post
      client_secret: abc123...
YAML
)

憑證會依所提供的內容儲存，直到 session 執行期間才會進行驗證。無效的憑證會在 session 期間以驗證錯誤或下游錯誤的形式呈現，該錯誤會被發出，但不會阻止 session 繼續進行。

限制條件：

• 每個 vault 內鍵必須唯一。 mcp_server_url（MCP 憑證）與 secret_name（環境變數憑證）在 vault 內的有效憑證之間必須唯一。建立重複項目會傳回 409。
• 鍵不可變更。 若要變更 mcp_server_url 或 secret_name，請封存該憑證並建立新的憑證。
• 每個 vault 最多 20 個憑證。

在建立 session 時參照 vault

建立 session 時傳入 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 相符時，會嘗試以未驗證的方式連線，若伺服器要求驗證則會發生錯誤。
• 當多個 vault 包含相符的憑證時，以第一個相符的 vault 為準。
• 在多代理 session 中，vault 憑證適用於每個執行緒。自身定義中宣告了相符 MCP 伺服器的代理會使用這些憑證進行驗證。請參閱將代理連線至 MCP 伺服器。

輪替憑證

機密值、display_name 以及（環境變數憑證上的）injection_location 可以更新。injection_location 的更新會依欄位合併，如新增憑證的「環境變數」分頁所述。對於執行中的 session，injection_location 的更新會以與機密輪替相同的方式傳播：session 的憑證會在不重新啟動的情況下重新解析，如憑證生命週期所述，而更新後的位置會套用至該 session 後續的對外請求。結構性欄位（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

憑證生命週期

憑證會定期重新解析，無論是在 session 期間還是在 vault 生命週期期間。這可確保憑證的輪替、封存或刪除能在不重新啟動的情況下傳播至執行中的 session。

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

對於 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
  }
}

其他操作

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