ボールトによる認証

「vault」（ボールト）と「credential」（認証情報）は認証のプリミティブであり、サードパーティサービスの認証情報を一度登録すれば、セッション作成時にIDで参照できるようになります。これにより、独自のシークレットストアを運用したり、呼び出しごとにトークンを送信したり、エージェントがどのエンドユーザーの代理として動作したかを見失ったりする必要がなくなります。

ボールト参照はセッションごとのパラメータであるため、プロダクトを agent リソースの粒度で、ユーザーを session リソースの粒度で管理できます。



ボールトを作成する

ボールトは、エンドユーザーに関連付けられた 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

レスポンスは完全なボールトレコードです。

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



認証情報を追加する

2つの認証情報カテゴリがサポートされています。

• MCP認証情報（mcp_oauth、static_bearer）：各認証情報は mcp_server_url をキーとします。セッション実行時にエージェントがそのURLのサーバーに接続すると、トークンが自動的に注入されます。
• 環境変数（environment_variable）：各認証情報は secret_name（環境変数名）をキーとし、サンドボックス内に不透明なプレースホルダーとして保存されます。エージェントがアウトバウンドリクエストを開始すると、不透明なプレースホルダーは出口（egress）で実際のシークレットに置換されます。エージェントがシークレット値を見ることはありません。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
)

認証情報は提供されたまま保存され、セッション実行時まで検証されません。無効な認証情報は、セッション中に認証エラーまたはダウンストリームエラーとして表面化します。これは発行されますが、セッションの継続をブロックしません。

制約：

• ボールトごとに一意のキー。 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_server_url で一致するMCP認証情報がない場合、接続は認証なしで試行され、サーバーが認証を要求する場合はエラーになります。
• 複数のボールトに一致する認証情報が含まれている場合、最初に一致したボールトが優先されます。
• マルチエージェントセッションでは、ボールト認証情報はすべてのスレッドに適用されます。自身の定義で一致する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



認証情報のライフサイクル

認証情報は、セッション中およびボールトのライフサイクル中の両方で定期的に再解決されます。これにより、認証情報のローテーション、アーカイブ、または削除が、再起動なしで実行中のセッションに伝播されます。

認証情報がアーカイブ、削除、またはリフレッシュに失敗した場合に通知を受け取るには、それらのライフサイクル変更に関連付けられたボールトおよび認証情報の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
  }
}



その他の操作

• ボールトまたは認証情報を一覧表示する： ページネーションされ、新しい順に表示されます。アーカイブされたレコードはデフォルトで除外されます（含めるには include_archived=true を渡します）。
• ボールトをアーカイブする： POST /v1/vaults/{id}/archive。すべての認証情報にカスケードします。シークレットはパージされ、レコードは監査のために保持されます。このボールトを参照する今後のセッションは失敗し、実行中のセッションは継続します。
• 認証情報をアーカイブする： POST /v1/vaults/{id}/credentials/{cred_id}/archive。シークレットペイロードをパージします。認証情報キー（mcp_server_url または secret_name）は引き続き表示され、代替の認証情報用に解放されます。
• ボールトまたは認証情報を削除する： ハード削除。レコードは保持されません。監査証跡が必要な場合はアーカイブを使用してください。