Vault로 인증하기

"Vault"(볼트)와 "credential"(자격 증명)은 타사 서비스의 자격 증명을 한 번 등록한 후 세션 생성 시 ID로 참조할 수 있게 해주는 인증 기본 요소입니다. 이를 통해 자체 시크릿 저장소를 운영하거나, 모든 호출마다 토큰을 전송하거나, 에이전트가 어떤 최종 사용자를 대신하여 작업했는지 추적하지 못하는 상황을 방지할 수 있습니다.

Vault 참조는 세션별 매개변수이므로, 제품은 agent 리소스 단위로 관리하고 사용자는 session 리소스 단위로 관리할 수 있습니다.



Vault 생성하기

Vault는 최종 사용자와 연결된 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..."

응답은 전체 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을 키로 사용합니다. 에이전트가 세션 런타임에 해당 URL의 서버에 연결하면 토큰이 자동으로 주입됩니다.
• 환경 변수 (environment_variable): 각 자격 증명은 secret_name(환경 변수 이름)을 키로 사용하며, 샌드박스에 불투명한 플레이스홀더로 저장됩니다. 에이전트가 아웃바운드 요청을 시작하면 불투명한 플레이스홀더가 이그레스(egress) 시점에 실제 시크릿으로 대체됩니다. 에이전트는 시크릿 값을 절대 볼 수 없습니다. CLI, SDK 또는 직접 API 호출과 같이 환경 변수를 통해 인증하는 모든 서비스에 이 방식을 사용하세요.

제공하는 실제 자격 증명 값(token, access_token, refresh_token, client_secret, secret_value)은 민감한 쓰기 전용 필드로 처리되며 API 응답에서 절대 반환되지 않습니다.

자격 증명은 제공된 그대로 저장되며 세션 런타임까지 검증되지 않습니다. 유효하지 않은 자격 증명은 세션 중에 인증 또는 다운스트림 오류로 나타나며, 이는 발생하지만 세션이 계속 진행되는 것을 차단하지 않습니다.

제약 사항:

• Vault당 고유 키. mcp_server_url(MCP 자격 증명)과 secret_name(환경 변수 자격 증명)은 vault 내 활성 자격 증명 중에서 고유해야 합니다. 중복을 생성하면 409가 반환됩니다.
• 키는 변경 불가능합니다. mcp_server_url 또는 secret_name을 변경하려면 자격 증명을 아카이브하고 새로 생성하세요.
• Vault당 최대 20개의 자격 증명.



세션 생성 시 vault 참조하기

세션을 생성할 때 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 자격 증명이 없는 경우, 인증 없이 연결이 시도되며 서버가 인증을 요구하면 오류가 발생합니다.
• 여러 vault에 일치하는 자격 증명이 포함된 경우, 일치하는 항목이 있는 첫 번째 vault가 우선합니다.
• 멀티 에이전트 세션에서는 vault 자격 증명이 모든 스레드에 적용됩니다. 자체 정의에서 일치하는 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



자격 증명 수명 주기

자격 증명은 세션 중과 vault 수명 주기 동안 모두 주기적으로 다시 해결됩니다. 이를 통해 자격 증명 교체, 아카이브 또는 삭제가 재시작 없이 실행 중인 세션에 전파됩니다.

자격 증명이 아카이브되거나 삭제되거나 갱신에 실패할 때 알림을 받으려면, 해당 수명 주기 변경과 관련된 vault 및 자격 증명 웹훅을 구독할 수 있습니다.

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를 참조하는 향후 세션은 실패하며, 실행 중인 세션은 계속됩니다.
• 자격 증명 아카이브: POST /v1/vaults/{id}/credentials/{cred_id}/archive. 시크릿 페이로드를 제거합니다. 자격 증명 키(mcp_server_url 또는 secret_name)는 계속 표시되며 대체 자격 증명을 위해 해제됩니다.
• Vault 또는 자격 증명 삭제: 하드 삭제입니다. 레코드가 유지되지 않습니다. 감사 추적이 필요한 경우 아카이브를 사용하세요.