볼트로 인증하기

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

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



볼트 생성

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

응답은 전체 볼트 레코드입니다:

{
  "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 응답에서 절대 반환되지 않습니다.

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을 변경하려면 자격 증명을 보관(archive)하고 새로 생성하세요.
• 볼트당 최대 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 업데이트는 자격 증명 추가의 Environment variable 탭에 설명된 대로 필드별로 병합됩니다. 실행 중인 세션의 경우, 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



자격 증명 수명 주기

자격 증명은 세션 중과 볼트 수명 주기 동안 주기적으로 다시 해석됩니다. 이를 통해 자격 증명 교체, 보관 또는 삭제가 재시작 없이 실행 중인 세션에 전파됩니다.

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

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)는 계속 표시되며 대체 자격 증명을 위해 해제됩니다.
• 볼트 또는 자격 증명 삭제: 완전 삭제입니다. 레코드가 보존되지 않습니다. 감사 추적이 필요한 경우 보관을 사용하세요.