Claude Platform Docs
Managed Agentsエージェントへの作業の委任

ボールトによる認証

セッション作成時にユーザーごとの認証情報を登録します。

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

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

ボールトを作成する

ボールトは、エンドユーザーに関連付けられた credentials のコレクションです。display_name を付け、必要に応じて metadata でタグ付けすることで、自社のユーザーレコードに対応付けられるようにします。

vault = client.beta.vaults.create(
    display_name="Alice",
    metadata={"external_user_id": "usr_abc123"},
)
print(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
}

認証情報を追加する

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

  • 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サーバーがOAuth 2.0を使用する場合は mcp_oauth を使用します。refresh ブロックを指定すると、アクセストークンの有効期限が切れた際にAnthropicが代わりにリフレッシュを行います。

refresh.token_endpoint_auth.type フィールドは、リフレッシュ呼び出しの認証方法を示します。

  • none：パブリッククライアント
  • client_secret_basic：クライアントシークレットによるHTTP Basic認証
  • client_secret_post：POSTボディ内のクライアントシークレット
credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Alice's Slack",
    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.user.access",
            "client_id": "1234567890.0987654321",
            "scope": "channels:read chat:write",
            "refresh_token": "xoxe-1-...",
            "token_endpoint_auth": {"type": "client_secret_post", "client_secret": "abc123..."},
        },
    },
)

refresh.token_endpoint には、リフレッシュトークンを発行したOAuthフローのトークンエンドポイントを設定してください。AnthropicはすべてのリフレッシュリクエストをそのURLに送信し、このフィールドは認証情報の作成後に変更できないためです。

認証情報は指定されたとおりに保存され、セッション実行時まで検証されません。無効な認証情報は、セッション中に認証エラーまたは下流のエラーとして表面化します。このエラーは発行されますが、セッションの継続を妨げることはありません。

制約：

  • ボールトごとに一意のキー。 mcp_server_url（MCP認証情報）と secret_name（環境変数の認証情報）は、ボールト内のアクティブな認証情報の間で一意である必要があります。重複を作成すると409が返されます。
  • キーは不変。 mcp_server_url または secret_name を変更するには、認証情報をアーカイブして新しいものを作成してください。
  • ボールトごとに最大20個の認証情報。

セッション作成時にボールトを参照する

セッション作成時に vault_ids を渡します。

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

実行時の動作：

  • mcp_server_url で一致するMCP認証情報がない場合、接続は認証なしで試行され、サーバーが認証を必要とする場合はエラーになります。
  • 複数のボールトに一致する認証情報が含まれている場合、最初に一致したボールトが優先されます。
  • マルチエージェントセッションでは、ボールトの認証情報はすべてのスレッドに適用されます。自身の定義で一致するMCPサーバーを宣言しているエージェントは、これらの認証情報で認証します。エージェントをMCPサーバーに接続するを参照してください。

認証情報をローテーションする

シークレットの値、display_name、および（環境変数の認証情報では）injection_location を更新できます。injection_location の更新は、認証情報を追加するの「環境変数」タブで説明したとおり、フィールドごとにマージされます。実行中のセッションでは、injection_location の更新はシークレットのローテーションと同じ方法で伝播します。認証情報のライフサイクルで説明するとおり、セッションの認証情報は再起動なしで再解決され、更新された場所はセッションのその後のアウトバウンドリクエストに適用されます。構造的なフィールド（mcp_server_url、secret_name、token_endpoint、client_id）は作成後にロックされます。これらを変更するには、認証情報をアーカイブして新しいものを作成してください。

client.beta.vaults.credentials.update(
    credential.id,
    vault_id=vault.id,
    auth={
        "type": "mcp_oauth",
        "access_token": "xoxp-new-...",
        "expires_at": "2099-12-31T23:59:59Z",
        "refresh": {"refresh_token": "xoxe-1-new-..."},
    },
)

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

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

認証情報がアーカイブされた、削除された、またはリフレッシュに失敗した場合に通知を受けるには、それらのライフサイクルの変更に関連付けられたボールトおよび認証情報のWebhookをサブスクライブできます。

イベントトリガー
vault.archivedボールトがアーカイブされました。配下の各認証情報に対しても vault_credential.archived イベントが発行されます。
vault.deletedボールトが削除されました。配下の各認証情報に対しても vault_credential.deleted イベントが発行されます。
vault_credential.archived認証情報が、直接またはボールトのアーカイブの結果としてアーカイブされました。
vault_credential.deleted認証情報が、直接またはボールトの削除の結果として削除されました。
vault_credential.refresh_failedmcp_oauth 認証情報をリフレッシュできません（無効なリフレッシュトークン、またはOAuthサーバーからの回復不能なエラー）。

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、またはネットワーク障害）。待機して再試行してください。
validation = client.beta.vaults.credentials.mcp_oauth_validate(
    credential.id,
    vault_id=vault.id,
)
print(validation.status)  # "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）は引き続き表示され、代替の認証情報のために解放されます。
  • ボールトまたは認証情報の削除： ハードデリートです。レコードは保持されません。監査証跡が必要な場合はアーカイブを使用してください。

Was this page helpful?