최종 고객 귀속을 위한 사용자 프로필

"User profile"(사용자 프로필, 이하 "프로필")은 각 API 요청이 귀하의 최종 고객 중 누구를 위한 것인지 Anthropic에 알려 줍니다. 그러면 보류나 차단과 같은 "safety enforcement action"(안전 시행 조치)이 조직 전체가 아닌 한 명의 최종 고객에게만 적용될 수 있습니다. 이 경우 나머지 트래픽은 영향을 받지 않습니다.

플랫폼이나 게이트웨이를 운영하거나 API 액세스를 재판매하는 경우, 최종 고객을 위해 보내는 요청은 귀하의 조직 아래로 도착합니다. Anthropic은 API 트래픽에 대해 자동화된 안전 분류기를 실행합니다. 요청에 프로필이 없으면 한 명의 최종 고객이 조직 전체에 적용되는 시행 조치를 유발할 수 있습니다.

각 최종 고객을 POST /v1/user_profiles로 한 번 등록하고 반환되는 uprof_ ID를 저장합니다. 그런 다음 해당 최종 고객을 대신하여 보내는 모든 요청의 anthropic-user-profile-id 헤더에 그 ID를 보냅니다.

프로필은 과금 대상이 아니며 가격에 영향을 주지 않습니다.

프로필을 받을 대상 결정하기

프로필이 무엇을 나타내는지는 Claude를 판매하는 방식에 따라 달라집니다. 즉, 귀하의 제품을 사용하는 개인이거나, 귀하가 API 액세스를 재판매하는 대상 회사입니다. 이 두 가지 경우가 대부분의 플랫폼에 해당합니다. 프로필의 access_type 필드가 어느 쪽에 해당하는지를 나타냅니다.

프로필에 포함되는 내용과 Anthropic의 사용 방식

프로필에는 최종 고객에 대해 귀하가 보낸 정보와 Anthropic이 설정한 프로그램 상태만 포함됩니다. 대화 내용은 포함되지 않습니다. Anthropic은 귀하가 보낸 세부 정보를 요청 귀속, 악용 모니터링, 사용 정책 시행에, 그리고 신뢰할 수 있는 액세스 프로그램에 대한 신청 및 액세스를 가능하게 하는 데 사용합니다. Anthropic은 이 세부 정보를 검증하지 않습니다.

Anthropic은 개인정보 처리방침에 따라 프로필을 처리합니다.

시작하기 전에

프로필은 다음 중 하나에서 생성하고 관리합니다.

• Claude API의 조직.
• Claude Platform on AWS의 조직. 호출하는 주체에게 사용자 프로필 IAM 작업 권한이 필요합니다.
• Azure에서 호스팅되는 배포가 아닌, Anthropic에서 호스팅되는 Microsoft Foundry 배포. Claude API나 Claude Platform on AWS의 조직은 필요하지 않습니다. 추론에 사용하는 것과 동일한 기본 URL 및 인증으로 Foundry 엔드포인트를 사용하세요.

Amazon Bedrock과 Google Cloud에는 /v1/user_profiles 엔드포인트가 없습니다. 추론을 그곳에서 실행하는 경우, Claude API 또는 Claude Platform on AWS의 조직에서 프로필을 생성하세요. Amazon Bedrock에서 프로필은 Claude in Amazon Bedrock에서만 작동합니다. Amazon Bedrock 및 Google Cloud에서 요청 귀속하기를 참조하세요.

최종 고객을 위해 보내는 트래픽은 한 조직에, 귀하 자신의 내부 사용량은 다른 조직에 두세요. 프로필은 워크스페이스가 아닌 조직에 속하므로, 한 조직 내에서 워크스페이스를 분리하는 것만으로는 충분하지 않습니다. 사용자 프로필은 최종 고객 트래픽용 조직에만 필요합니다. Claude API에서 다른 조직을 만들려면 Claude 고객센터의 Creating and managing Workspaces in the Claude Console에서 "How to create a new organization" 섹션을 참조하세요.

예제는 API 키로 Claude API를 호출합니다. Admin API 키는 필요하지 않습니다. Claude Platform on AWS에서는 해당 플랫폼의 기본 URL과 인증을 사용하세요.

각 최종 고객에 대한 프로필 생성하기

Claude로 트래픽을 보내는 최종 고객마다 프로필을 하나씩 생성하세요. 고객 온보딩 흐름에서 한 번만 생성합니다. POST /v1/user_profiles는 "idempotent"(멱등)하지 않으므로, reference_id가 기존 프로필과 일치하더라도 호출할 때마다 새 프로필이 생성됩니다. 프로필이 없는 최종 고객이 이미 있다면, 이 섹션 뒷부분의 기존 고객 기반 등록에 관한 안내를 참조하세요.

다음 예제는 게이트웨이를 통해 API 액세스를 구매하는 회사를 등록하므로 access_type을 passthrough로 설정합니다. application 프로필의 경우 access_type을 생략하고, name과 external_user_details에 회사 대신 한 명의 최종 사용자를 기술하세요. 프로필을 받을 대상 결정하기에서 두 가지 액세스 유형을 비교합니다.

client = anthropic.Anthropic()

profile = client.user_profiles.create(
    name="Acme Analytics, Inc.",
    access_type="passthrough",
    external_user_details={"reference_id": "cust-8f2a1c", "country": "US"},
)

print(profile.id)

응답은 새 프로필입니다.

{
  "type": "user_profile",
  "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "name": "Acme Analytics, Inc.",
  "access_type": "passthrough",
  "external_user_details": {
    "reference_id": "cust-8f2a1c",
    "onboarded_at": null,
    "account_status": null,
    "entity_type": null,
    "country": "US",
    "name_hash": null,
    "email_hash": null
  },
  "metadata": {},
  "programs": {
    "cyber": null,
    "efs": null
  },
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z"
}

id를 고객 레코드에 저장하고, 서비스 인스턴스가 자체 프로필을 생성하는 대신 그곳에서 읽도록 하세요. 프로필의 조회, 업데이트, 삭제는 해당 id로 수행합니다. programs 필드는 읽기 전용이며 귀속에는 사용되지 않습니다. 이 필드에는 Anthropic이 운영하는 각 프로그램에서의 최종 고객 상태가 담깁니다. 값의 의미는 프로필에 적용되는 프로그램을 참조하세요.

조직 내 프로필 수에는 상한이 없지만, 프로필 생성에는 속도 제한이 적용됩니다. 기존 고객 기반을 대량으로 등록하기 전에 Anthropic 계정 팀에 문의하세요.

최종 고객에 대해 Anthropic에 알릴 내용

모든 필드는 선택 사항입니다. name, metadata, 그리고 external_user_details의 다음 필드를 보낼 수 있습니다: entity_type, country, reference_id, onboarded_at, account_status, name_hash, email_hash. 프로필 생성 레퍼런스에서 각 필드의 유형, 형식, 길이 제한을 설명합니다.

필드를 설정할 때 다음 규칙을 따르세요.

• 알 수 없는 값: 값을 모르는 경우 자리 표시자를 보내지 말고 생략하세요. external_user_details의 값은 나중에 교체할 수 있지만 지울 수는 없습니다.
• 회사 이름: passthrough 프로필의 경우, 알고 있다면 회사의 법적 명칭을 name에 보내세요.
• 국가: country에는 귀하의 국가가 아닌 최종 고객의 국가를 보내세요.
• 자체 ID: reference_id에는 최종 고객에 대한 귀하 자신의 안정적인 식별자를 보내세요. 고유할 필요는 없습니다.
• 공유할 수 없는 이름과 이메일 주소: name을 생략하고 대신 external_user_details.name_hash를 보내세요. 이메일 주소의 경우 external_user_details.email_hash를 보내세요. 프로필에는 주소 자체를 위한 필드가 없습니다.
• 해시: 해시는 귀하가 선택한 함수로 직접 계산하세요. 해시는 귀하의 프로필 중 어떤 프로필이 이름이나 이메일 주소를 공유하는지 Anthropic에 보여 줍니다. 동일한 방식으로 계산된 값만 일치하므로, 모든 프로필에 동일한 함수와 동일한 대소문자 및 공백 정규화를 사용하세요.

각 요청 귀속하기

최종 고객을 대신하여 보내는 모든 요청의 anthropic-user-profile-id 헤더에 프로필 ID를 보내세요. SDK와 CLI에는 헤더를 대신 보내 주는 인수가 있습니다: user_profile_id.

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    user_profile_id="uprof_011CZkZCu8hGbp5mYRQgUmz9",
)

print(message)

이 헤더는 토큰 카운팅, Message Batches, OpenAI SDK 호환성 요청에서도 동일하게 작동합니다. 배치에서는 배치 내 모든 요청에 적용됩니다.

Claude API, Claude Platform on AWS, 그리고 Anthropic에서 호스팅되는 Microsoft Foundry 배포는 모든 요청에서 ID를 확인합니다. ID의 형식이 잘못되었거나 요청을 보내는 조직에 속하지 않으면 API는 400 invalid_request_error를 반환합니다. 기본적으로 이러한 플랫폼은 프로필을 생성한 조직의 요청에서만 프로필 ID를 허용합니다. 즉, 예를 들어 Claude API의 조직 하나와 Claude Platform on AWS의 조직 하나처럼 둘 이상의 조직으로 트래픽을 보내는 경우, 프로필을 생성하지 않은 조직의 요청은 동일한 400을 받습니다.

Message Batches는 예외입니다. 배치를 생성할 때는 ID의 형식만 확인합니다. 형식이 올바른 ID가 배치를 보내는 조직에 속하지 않더라도 배치는 생성되며, 이후 배치 내 각 요청은 동일한 invalid_request_error를 포함하는 errored 결과로 실패합니다.

Amazon Bedrock 및 Google Cloud에서 요청 귀속하기

두 액세스 유형의 프로필 ID 모두 Claude in Amazon Bedrock과 Google Cloud에서도 작동합니다. InvokeModel 또는 Converse로 호출하는 이전 Amazon Bedrock 통합에서는 작동하지 않습니다. Anthropic 조직의 자격 증명은 프로필을 생성하고 관리하는 데만 사용합니다. 추론은 기존 AWS 또는 Google Cloud 자격 증명을 그대로 사용합니다.

Claude in Amazon Bedrock에서는 ID를 요청 본문의 최상위 수준에 넣으세요.

{
  "model": "anthropic.claude-opus-5-5",
  "max_tokens": 1024,
  "user_profile_id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "messages": [{ "role": "user", "content": "Hello, Claude" }]
}

Claude in Amazon Bedrock으로 요청을 보내는 각 AWS 계정과 Google Cloud에서 요청을 보내는 각 Google Cloud 프로젝트를 프로필을 생성하는 Anthropic 조직에 연결하세요.

1. 해당 조직의 관리자 또는 소유자가 portal.anthropic.com에 있는 Verification Portal의 Linked accounts에서 연결을 시작합니다.
2. AWS 계정 또는 Google Cloud 프로젝트에서 IAM을 관리할 수 있는 사람이 포털에서 제공하는 명령을 실행합니다.
3. 관리자 또는 소유자가 포털에서 확인을 완료합니다.

프로필에 적용되는 프로그램은 계정이 연결되고 포털에 Linked로 표시된 후에만 해당 계정의 요청에 적용됩니다. 이러한 프로그램에는 최종 고객이 프로필을 해당 조직에 연결한 후 최종 고객의 조직이 승인받은 프로그램이 포함됩니다.

Claude in Amazon Bedrock과 Google Cloud는 ID의 형식을 확인하지만 프로필을 조회하지는 않습니다. 형식이 잘못된 ID는 400으로 거부합니다. 형식이 올바른 ID는 모두 허용하므로, 성공적인 응답이 ID가 프로필과 일치함을 확인해 주지는 않습니다. ID가 없는 요청은 귀속되지 않은 채 처리되며, 시행 조치를 유발하면 그 조치는 조직 전체에 적용됩니다.

회사 내 개별 사용자 식별하기

passthrough 프로필은 요청을 하는 개인이 아니라 회사를 식별합니다. 요청이 식별 가능한 한 개인에게서 오는 경우, Messages 요청의 metadata.user_id 필드에 해당 개인의 식별자도 함께 보내세요. 이는 프로필의 metadata 필드가 아니라 요청 자체의 metadata 객체입니다. 이 식별자는 선택 사항이며, Anthropic이 한 개인의 오용을 탐지하는 데 도움이 됩니다.

프로필을 최신 상태로 유지하기

최종 고객의 세부 정보나 계정 상태가 변경되면 프로필을 업데이트하고, 최종 고객이 계정을 해지하거나 데이터 삭제를 요청하면 프로필을 삭제하세요.

프로필 업데이트하기

POST /v1/user_profiles/{id}는 보낸 필드만 변경합니다. 예를 들어 회사가 브랜드를 변경하거나 귀하가 계정을 정지할 때 사용하세요.

• name과 access_type은 저장된 값을 대체합니다.
• external_user_details에 보내는 각 필드는 저장된 값을 대체합니다. 값을 지울 수는 없습니다. API는 null을 400으로 거부합니다.
• metadata는 키 단위로 병합됩니다. 보낸 키는 저장된 값을 덮어쓰고, 빈 문자열은 키를 삭제하며, 생략한 키는 그대로 유지됩니다.

다음 예제는 계정을 정지됨으로 표시하고 trial_cohort 메타데이터 키를 제거합니다.

client = anthropic.Anthropic()

profile = client.user_profiles.update(
    "uprof_011CZkZCu8hGbp5mYRQgUmz9",
    external_user_details={"account_status": "suspended"},
    metadata={"trial_cohort": ""},
)

print(profile)

프로필 삭제하기

DELETE /v1/user_profiles/{id}는 프로필과 name, external_user_details, metadata를 포함하여 해당 프로필에 대해 귀하가 제공한 모든 정보를 영구적으로 삭제합니다. Anthropic이 해당 프로필 ID에 대해 보관하는 신뢰 및 안전 기록은 삭제되지 않습니다.

최종 고객이 계정을 해지하거나 데이터 삭제를 요청하면 프로필을 삭제하세요. 프로필을 삭제하기 전에 해당 최종 고객의 요청에 그 ID를 보내는 것을 중단하세요. 삭제 요청 후에도 최종 고객이 계속 서비스를 이용하는 경우, 새 프로필을 생성하고 그 ID로 전환하세요. 그런 다음 이전 프로필을 삭제하세요.

client = anthropic.Anthropic()

deleted = client.user_profiles.delete("uprof_011CZkZCu8hGbp5mYRQgUmz9")

print(deleted.id)

응답은 "type": "user_profile_deleted"와 함께 ID를 반복합니다. 삭제 요청이 서버 오류를 반환하면 다시 시도하세요. 재시도에서 404가 반환되면 첫 번째 삭제가 처리된 것입니다.

삭제 후 프로필 엔드포인트는 해당 ID에 대해 404를 반환합니다. 최대 약 10분 동안은 삭제된 ID를 포함한 추론 요청이 여전히 성공할 수 있습니다. 그 이후에는 모든 요청에서 ID를 확인하는 플랫폼이 해당 요청을 400으로 거부합니다. Claude in Amazon Bedrock과 Google Cloud는 프로필을 조회하지 않으므로 여전히 요청을 허용합니다.

다음 단계

API 레퍼런스에서 각 엔드포인트의 필드, 유형, 제한을 확인할 수 있습니다: 프로필 생성, 프로필 조회, 프로필 업데이트, 프로필 목록.

최종 고객이 귀하의 플랫폼을 통해 Claude를 사용할 때 해당 고객의 프로그램 승인이 적용되어야 한다면, 최종 고객에게 Verification Portal 링크 보내기를 참조하세요.