Vault로 인증하기

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

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



Vault 생성하기

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

응답은 전체 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
}



Credential 추가하기

두 가지 credential 카테고리가 지원됩니다:

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

제공하는 실제 credential 값(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
)

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

제약 사항:

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



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



Credential 교체하기

시크릿 값, display_name, 그리고 (환경 변수 credential의 경우) injection_location을 업데이트할 수 있습니다. injection_location 업데이트는 Credential 추가하기의 환경 변수 탭에 설명된 대로 필드별로 병합됩니다. 실행 중인 세션의 경우, injection_location 업데이트는 시크릿 교체와 동일한 방식으로 전파됩니다. Credential 수명 주기에 설명된 대로 세션의 credential이 재시작 없이 다시 해결되며, 업데이트된 위치는 세션의 이후 아웃바운드 요청에 적용됩니다. 구조적 필드(mcp_server_url, secret_name, token_endpoint, client_id)는 생성 후 잠깁니다. 이를 변경하려면 credential을 아카이브하고 새로 생성하세요.

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



Credential 수명 주기

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

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

mcp_oauth credential의 경우, 재해결 시 액세스 토큰이 만료되었다면 토큰도 갱신됩니다. 갱신이 실패하면 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: grant가 사라졌거나 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 또는 credential 나열: 페이지네이션되며 최신순으로 정렬됩니다. 아카이브된 레코드는 기본적으로 제외됩니다(포함하려면 include_archived=true를 전달하세요).
• Vault 아카이브: POST /v1/vaults/{id}/archive. 모든 credential에 연쇄 적용됩니다. 시크릿은 제거되고 레코드는 감사를 위해 유지됩니다. 이 vault를 참조하는 향후 세션은 실패하며, 실행 중인 세션은 계속됩니다.
• Credential 아카이브: POST /v1/vaults/{id}/credentials/{cred_id}/archive. 시크릿 페이로드를 제거합니다. Credential 키(mcp_server_url 또는 secret_name)는 계속 표시되며 대체 credential을 위해 해제됩니다.
• Vault 또는 credential 삭제: 하드 삭제입니다. 레코드가 유지되지 않습니다. 감사 추적이 필요한 경우 아카이브를 사용하세요.