볼트로 인증하기

"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
}

자격 증명 추가하기

두 가지 자격 증명 범주가 지원됩니다:

• 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 = 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..."},
        },
    },
)

bearer_credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Linear API key",
    auth={
        "type": "static_bearer",
        "mcp_server_url": "https://mcp.linear.app/mcp",
        "token": "lin_api_your_linear_key",
    },
)

env_credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Notion API key for sandbox",
    auth={
        "type": "environment_variable",
        "secret_name": "NOTION_API_KEY",
        "secret_value": "ntn_your-secret-here",
        "networking": {
            "type": "limited",
            "allowed_hosts": ["api.notion.com"],
        },
        "injection_location": {"header": True},
    },
)
if env_credential.auth.type == "environment_variable":
    location = env_credential.auth.injection_location
    print(f"header: {location.header}, body: {location.body}")  # header: True, body: False

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

제약 사항:

• 볼트당 고유 키. 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-..."},
    },
)

자격 증명 수명 주기

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

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

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