볼트로 인증하기

볼트와 자격 증명은 서드파티 서비스에 대한 자격 증명을 한 번 등록하고 세션 생성 시 ID로 참조할 수 있게 해주는 인증 기본 요소입니다. 이를 통해 자체 시크릿 저장소를 운영하거나, 모든 호출마다 토큰을 전송하거나, 에이전트가 어떤 최종 사용자를 대신하여 행동했는지 추적을 잃어버릴 필요가 없습니다.

볼트 참조는 세션별 파라미터이므로, 에이전트 수준에서 제품을 관리하고 세션 수준에서 사용자를 관리할 수 있습니다.

볼트 생성

볼트는 최종 사용자와 연결된 credentials의 모음입니다. display_name을 지정하고 선택적으로 metadata로 태그를 달아 자체 사용자 레코드에 다시 매핑할 수 있습니다.

vault_id=$(curl --fail-with-body -sS https://api.anthropic.com/v1/vaults \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF' | jq -r '.id'
{
  "display_name": "Alice",
  "metadata": {"external_user_id": "usr_abc123"}
}
EOF
)
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_server_url에 바인딩됩니다. 에이전트가 세션 런타임에 MCP 서버에 연결할 때, API는 서버 URL을 참조된 볼트의 활성 자격 증명과 대조하여 토큰을 주입합니다.

자격 증명은 제공된 대로 저장되며 세션 런타임까지 검증되지 않습니다. 잘못된 토큰은 세션 중 MCP 인증 오류로 표시되며, 이는 방출되지만 세션이 계속되는 것을 차단하지 않습니다.

제약 사항:

• 볼트당 mcp_server_url당 하나의 활성 자격 증명. 동일한 URL에 대해 두 번째 자격 증명을 생성하면 409가 반환됩니다.
• mcp_server_url은 변경 불가능합니다. 다른 서버를 가리키려면 이 자격 증명을 보관하고 새 자격 증명을 생성하세요.
• 볼트당 최대 20개의 자격 증명. 이는 에이전트당 최대 MCP 서버 수와 일치합니다.

자격 증명 교체

시크릿 페이로드와 일부 메타데이터 필드만 변경 가능합니다. mcp_server_url, token_endpoint, client_id는 생성 후 잠깁니다.

세션 생성 시 볼트 참조

세션 생성 시 vault_ids를 전달하세요:

런타임 동작:

• 자격 증명은 세션 중 주기적으로 재확인되므로, 교체 또는 보관이 재시작 없이 실행 중인 세션에 전파됩니다.
• 볼트에 MCP 서버에 대한 자격 증명이 없으면 인증 없이 연결이 시도되고 오류가 발생합니다.
• 여러 볼트가 MCP 서버를 포함하는 경우, 일치하는 첫 번째 볼트가 우선합니다.

기타 작업

• 볼트 또는 자격 증명 목록 조회: 페이지네이션, 최신 순. 보관된 레코드는 기본적으로 제외됩니다(include_archived=true를 전달하면 포함됩니다).
• 볼트 보관: POST /v1/vaults/{id}/archive. 모든 자격 증명으로 계단식 적용됩니다. 시크릿은 제거되고 레코드는 감사를 위해 보존됩니다. 이 볼트를 참조하는 향후 세션은 실패하고, 실행 중인 세션은 계속됩니다.
• 자격 증명 보관: POST /v1/vaults/{id}/credentials/{cred_id}/archive. 시크릿 페이로드를 제거하고 mcp_server_url은 계속 표시됩니다. 대체 자격 증명을 위해 mcp_server_url을 해제합니다.
• 볼트 또는 자격 증명 삭제: 하드 삭제. 레코드가 보존되지 않습니다. 감사 추적이 필요한 경우 보관을 사용하세요.