Claude API 사용자 프로필 설정: 고객별 요청 연결과 제한 상태 조회

여러 고객의 요청을 같은 Claude API 조직에서 보내는 서비스라면 고객 프로필 생성 → ID 저장 → 요청에 연결 → 제한 상태 조회 순서로 구성하면 됩니다. Anthropic의 사용자 프로필은 각 요청이 어느 고객의 것인지 알려 주며, 고객 단위로 안전 조치를 적용할 수 있게 합니다.

여기서 제한은 안전 정책에 따른 조치를 뜻합니다. 요금 상한이나 토큰 사용량을 설정하는 기능과는 다릅니다. 이 글은 직접 Claude API를 호출하는 서비스를 대상으로 합니다.

주요 용어

용어의미

user_profiles	고객 식별 정보를 등록·조회하는 API 리소스
uprof_ ID	프로필 생성 응답으로 받는 고유 식별자
enforcement_status	Anthropic이 정한 안전 조치 상태
enforcement_actions	현재 열려 있는 안전 조치 목록

1. 고객 단위를 정하고 프로필 생성하기

Anthropic의 사용자 프로필 가이드는 제품의 개별 사용자를 application, API 접근을 재판매하는 고객 회사를 passthrough로 구분합니다. application이 기본값이며, 재판매 고객은 회사 단위로 프로필을 만듭니다.

아래는 문서 기반 미실행 예제입니다. Bash에서 API 키를 환경 변수로 준비했다고 가정하며, 실제 API 호출 결과를 검증한 코드는 아닙니다.

curl https://api.anthropic.com/v1/user_profiles \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "Content-Type: application/json" \
  -d '{"access_type":"application"}'

일반 API 키로 관리할 수 있어 Admin API 키는 필요하지 않습니다. name, metadata, external_user_details는 선택 입력입니다.

응답의 id를 서비스의 고객 레코드에 저장하세요. 같은 reference_id로 다시 생성해도 새 프로필이 생깁니다. 가입 처리나 재시도 로직에서는 저장된 ID가 있는지 먼저 확인하도록 설계하는 편이 좋습니다.

2. 고객 요청에 저장한 ID 연결하기

고객을 인증한 뒤 서버에서 해당 고객의 프로필 ID를 찾고, Claude API 요청에 다음 헤더를 추가합니다. 아래 ID는 자리표시자입니다.

anthropic-user-profile-id: uprof_REPLACE_WITH_SAVED_ID

SDK에서는 user_profile_id 인자로 연결할 수 있습니다. 고객이 보낸 임의의 ID를 그대로 사용하는 대신, 서버가 관리하는 고객 레코드에서 값을 가져오도록 구성하세요.

프로필은 조직에 속합니다. 잘못된 형식이나 다른 조직의 ID를 보내면 Claude API에서 400 오류가 발생할 수 있습니다. 내부 사용과 고객 트래픽은 조직을 분리하라는 것이 Anthropic의 안내입니다.

3. 제한 상태 조회하고 해석하기

개별 조회 경로는 GET /v1/user_profiles/{id}입니다. 앞선 예제와 같은 환경에서 저장한 ID를 USER_PROFILE_ID에 넣어 조회합니다. 이 코드도 미실행 예제입니다.

curl "https://api.anthropic.com/v1/user_profiles/$USER_PROFILE_ID" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21"

응답에서는 enforcement_status와 enforcement_actions를 함께 읽습니다. 서비스가 직접 기록하는 external_user_details.account_status와 달리, 이 두 필드는 Anthropic이 설정하며 직접 수정하는 값이 아닙니다.

가이드는 세 가지 상태를 설명하지만 API 참조에는 pending을 포함한 네 값이 정의되어 있습니다. 상태 처리 코드는 API 참조의 다음 우선순위를 기준으로 구성하세요.

상태판정 기준

banned	열린 ban이 있음
pending	신원 확인으로 해제 가능한 restriction에 고객이 확인을 제출해 심사 중이며, 열린 조치에 account_compromise 사유가 없음
restricted	위 조건에 해당하지 않고 열린 조치가 있음
unrestricted	열린 조치가 없음

unrestricted는 현재 열린 조치가 없다는 뜻입니다. 앞으로 제한되지 않는다는 보장이나 조직 전체의 안전 상태 판정으로 쓰지는 마세요.

4. 목록 조회에서 놓치기 쉬운 조건

GET /v1/user_profiles는 enforcement_status 배열 필터를 지원합니다. 예를 들어 enforcement_status[]=restricted와 enforcement_status[]=banned를 함께 보내면 둘 중 하나에 해당하는 프로필을 반환합니다. 열린 조치가 있는 고객 전체를 점검하려면 pending도 포함해야 합니다.

필터를 사용하면 결과가 비어도 다음 페이지가 있을 수 있습니다. 응답의 next_page를 다음 요청의 page에 전달하고, next_page가 null일 때 끝내세요.

오래된 user-profiles-2026-09-04 이하 베타 헤더에서는 상태 필드가 빠집니다. 가이드는 user-profiles- 베타 값을 보내지 않도록 안내합니다. 또한 조치 변경이 updated_at을 반드시 바꾸지는 않으므로, 모니터링할 때는 두 상태 필드의 값을 비교해야 합니다.

먼저 고객 테이블에 프로필 ID를 저장하고, 인증된 고객의 API 요청에 헤더를 붙이는 흐름부터 연결하세요. 이후 개별 조회와 페이지 순회를 추가하면 고객별 안전 조치 상태를 서비스 운영 화면에서 다룰 수 있습니다.

참고 링크

• Anthropic — User profiles for end-customer attribution
• Anthropic — List User Profiles API 참조