Claude API 사용자 프로필: 고객별 제재 분리와 웹훅의 현재 한계

고객 한 명의 문제가 왜 서비스 전체의 문제가 되는가

문서 번역 서비스를 운영한다고 가정하자. 사용자는 각자 로그인하지만, 서버는 모든 번역 요청을 하나의 Claude API 조직으로 보낸다. 앱에는 누가 요청했는지 기록되어 있어도 공급자에게 그 구분을 전달하지 않으면, 공급자는 요청을 서비스 운영 조직의 트래픽으로 받아들인다.

Anthropic은 2026년 10월 20일 user profiles, 즉 최종 고객 귀속을 위한 사용자 프로필을 공개했다. 공급자의 안전 정책에 따른 제한이나 이용 금지를 특정 고객에게 적용할 수 있도록 하는 기능이다. 같은 날 조직 웹훅의 베타 등록 API도 안내했다. 10월 20일 릴리스

여기서 중요한 현재 조건이 있다. 10월 21일 확인한 조직 웹훅 본문에는 아직 이벤트를 전송하지 않는다는 안내가 있다. 등록 API가 있다는 사실만으로 고객 제재 알림이 운영 중이라고 설계하면 안 된다. 이 글은 직접 Claude API를 쓰는 서비스의 도입 판단을 다루며, 다른 클라우드 경로에 같은 계약이 적용된다고 가정하지 않는다. 웹훅의 현재 제공 상태

아래 번역 서비스와 회사들은 설명용 가정이다. 실제 고객 요청, 계정 제재, API 호출이나 통지를 시험하지 않았다. 독자가 가져갈 결과는 바로 배포할 코드가 아니라, 요청 귀속과 운영 상태를 빠뜨리지 않기 위한 설계표다.

프로필을 누구에게 하나씩 만들 것인가

이 기능의 출발점은 API 키를 더 만드는 일이 아니라 누가 최종 고객인가를 정하는 일이다. 공식 계약은 두 경우를 나눈다. 프로필 타입 정의

서비스 형태	프로필이 나타내는 대상	access_type
Claude를 내부에서 이용하는 번역 앱	앱에 가입한 사용자 한 명	application — 기본값
회사들에 API 접근을 재판매하는 게이트웨이	재판매를 받는 회사 한 곳	passthrough — 명시 필요

번역 앱의 사용자가 같은 회사 소속이라고 해서 무조건 회사 프로필 하나로 묶는 것은 이 구분에 맞지 않는다. 반대로 회사에 원시 추론 API를 재판매하는 경우에는 회사 안의 직원마다 별도 재판매 프로필을 만들라는 계약이 아니다. 과금 단위를 먼저 보고 추측하기보다 실제 제공하는 서비스 형태를 확인해야 한다.

프로필은 조직에 속하며 워크스페이스에 속하지 않는다. 공식 가이드는 고객용 트래픽과 자사 내부 사용을 서로 다른 조직으로 분리하라고 안내한다. 워크스페이스만 나누면 충분하다고 볼 수 없다. 고객·조직·워크스페이스의 관계

다만 프로필을 나눴다고 데이터베이스의 고객별 접근 권한이나 사용량 상한이 생기지는 않는다. 이 기능의 계약은 공급자에게 요청 주체를 알려 주는 것이다. 번역 문서의 소유권 검사, 고객별 대기열과 비용 정책은 서비스가 따로 설계해야 한다. 따라서 프로필은 다중 고객 서비스의 여러 경계 중 하나로 보는 편이 정확하다.

등록한 ID가 모든 요청까지 이어져야 한다

프로필 생성 응답의 uprof_ ID를 고객 레코드에 저장하고, 해당 고객을 대신한 요청에 anthropic-user-profile-id 헤더로 보낸다. 프로필 생성은 멱등하지 않아 같은 reference_id로 다시 호출해도 새 프로필이 생긴다. 생성과 요청 귀속 계약

이 제약에서 실무 설계가 나온다. 각 서버가 요청마다 프로필을 만들게 두면 고객 하나가 여러 공급자 ID로 갈라진다. 가입 처리에서 한 번 연결한 ID를 공통 고객 저장소에서 읽도록 하고, 동시에 가입 처리가 실행될 때 중복 생성되지 않도록 해야 한다. 생성 요청이 시간 초과됐다면 성공 여부가 불명확하므로 무작정 재생성하기 전에 운영 기록과 공급자 상태를 대조할 경로가 필요하다. 일반적인 재시도 판단은 시간 초과와 멱등성에서 더 자세히 설명했다.

또 하나의 설계 원칙은 클라이언트가 보낸 프로필 ID를 그대로 믿지 않는 것이다. 로그인한 사용자 A가 요청 본문에 B의 ID를 넣을 수 있다면, 서비스가 알고 있는 사용자와 공급자에게 보낸 귀속이 달라진다. 서버가 인증된 사용자와 저장된 프로필의 연결을 확인한 뒤 헤더를 만드는 구조가 적절하다. 이는 이 글의 권장 설계이며 프로필 API가 앱의 로그인 검사를 수행해 준다는 뜻이 아니다.

그림은 제품 화면이 아닌 설명용 구성도다. 요청 주체를 연결하는 위쪽 경로와 상태를 확인하는 아래쪽 경로를 나눴다. 오른쪽 공급자 ID가 있다고 왼쪽의 문서 접근 권한까지 얻는 구조가 아니다.

프로필 연결이 빠진 작업을 발견했을 때도 “일단 공용 계정으로 보낸다”를 기본 복구로 삼으면 분리 목적이 무너진다. 다음 설계표처럼 원인을 고친 뒤 같은 고객으로 재개하는 편이 낫다.

가상 서비스의 상태	제안하는 처리	확인할 결과
고객은 존재하지만 연결 ID가 없음	해당 고객 작업만 보류하고 연결 절차 확인	공용 ID로 조용히 넘어가지 않음
작업에 담긴 고객과 서버의 고객 레코드가 다름	전송 전 거절하고 작업 소유자 대조	다른 고객에게 귀속되지 않음
백그라운드 작업에는 ID가 있지만 웹 요청에는 없음	두 실행 경로의 공통 전송 계층 점검	동기·예약·재시도 요청에 같은 연결 적용

이 표의 보류 정책은 서비스 설계 제안이다. 공급자가 자동으로 같은 처리를 한다고 검증한 결과가 아니다.

배치가 요청을 묶으면 귀속도 함께 묶인다

하루 동안 쌓인 번역 작업을 묶어 보내면 효율적으로 보인다. 그러나 공식 가이드상 Message Batches의 프로필 헤더는 배치 안의 모든 요청에 적용된다. 서로 다른 고객의 작업을 한 배치로 섞는 것은 고객별 귀속과 맞지 않는다. 배치에 적용되는 프로필

가상의 대기열에 A-문서1, B-문서1, A-문서2가 들어 있다고 하자. 세 문서를 하나의 배치로 보내고 A의 프로필을 붙이면 B의 작업도 A에게 귀속된다. 이 서비스의 묶음 기준은 먼저 고객이어야 한다. A의 두 문서를 한 묶음, B의 문서를 별도 묶음으로 나눈 뒤 각자 프로필을 연결한다. 실제 배치 크기나 처리량 개선을 측정한 사례는 아니다.

배치 생성 응답만 보고 연결이 맞았다고 판정하는 것도 부족하다. 직접 Claude API의 일반 요청은 ID 형식과 조직 소속을 확인하지만, 배치 생성은 형식만 확인한다. 잘못된 조직의 ID라도 형식이 맞으면 배치는 생성되고 내부 요청 결과가 오류로 끝날 수 있다. 일반 요청과 배치의 검사 시점

따라서 운영 화면에 필요한 완료 조건은 “배치 접수됨” 다음의 개별 결과 확인이다. 어떤 고객의 몇 번째 문서가 실패했는지 연결할 수 있어야 동일 문서를 중복 처리하거나 엉뚱한 고객에게 실패를 안내하는 일을 피할 수 있다.

자사 계정 상태와 공급자 제재 상태를 합치지 않는다

운영자가 번역 앱에서 사용자를 일시 정지한 상태와 Anthropic이 정책상 제한한 상태는 다른 판단이다. 프로필의 external_user_details.account_status는 플랫폼이 신고하는 값이다. 이 값을 바꿔도 Anthropic의 결정이 바뀌는 것은 아니다. 계정 상태의 의미

가령 앱 이용료 문제로 자사 계정이 정지된 사용자가 있다고 하자. 공급자 제재가 없다는 이유만으로 번역을 다시 허용하면 자사의 운영 규칙을 건너뛴다. 반대로 앱에서 이용을 허용했더라도 공급자 제한이 남아 있다면 제한 이유에 맞는 대응이 필요하다. 한 개의 초록색 “활성” 배지로 두 상태를 합치면 담당자는 무엇을 해제해야 하는지 알 수 없다.

이 글이 제안하는 운영 기록은 다음 세 칸이다.

기록	답하는 질문	혼동하면 생기는 일
고객과 프로필의 연결	이 작업은 누구의 요청인가?	잘못된 고객에게 제재·문의가 연결됨
자사 이용 상태	우리 서비스가 이 고객의 작업을 허용하는가?	공급자 상태만 보고 자사 정지를 해제함
공급자 제재 상태와 확인 시각	공급자에게 적용 중인 제한을 확인했는가?	오래된 값이나 누락을 정상으로 표시함

공식 웹훅 문서상 제재 상태 필드는 조직에 해당 기능이 활성화되기 전에는 응답에 없다. 오래된 user-profiles-2026-09-04 또는 그 이전 베타 값을 사용해도 필드가 빠지는 조건이 있다. 따라서 필드 없음은 제한 없음과 같지 않다. 실제 조직의 제공 조건과 요청 버전을 먼저 확인해야 한다. 첫 이벤트 이전의 조건

웹훅은 지금 가동 상태부터, 이후에는 현재 상태부터 확인한다

현재는 이벤트 전송 미가동 안내가 있으므로, 등록 성공을 운영 알림 테스트의 성공으로 기록할 수 없다. 베타 접근도 별도 요청이 필요하다. 제재 상태 조회를 사용할 수 있는 조직인지 먼저 확인하고, 사용할 수 없다면 담당자 확인 절차를 준비해야 한다. 확인하지 못한 상태를 unrestricted로 채우면 안 된다.

향후 전송이 활성화될 때 준비할 계약도 구분해 읽을 수 있다. 문서의 이벤트는 프로필·제재 ID를 전달하며, 이벤트 도착 후 프로필의 현재 상태를 다시 조회하도록 안내한다. 전달은 지연되거나 순서가 바뀔 수 있다. 따라서 resolved 이벤트 하나를 받았다는 이유로 곧바로 이용을 재개하는 처리는 맞지 않는다. 이벤트 형식과 현재 상태 조회

예를 들어 제한 R1이 해제된 뒤 새 제한 R2가 생겼는데, R1 해제 통지가 늦게 도착했다고 가정하자. 이벤트 이름만 읽으면 “해제됨”이다. 현재 프로필에는 R2가 남아 있을 수 있다. 이때 필요한 행동은 이벤트를 계기로 다시 확인하는 것이다. 한 제재가 끝났다는 사실과 현재 모든 제재가 없다는 사실은 다르다. 이 시간표는 가상의 반례이며 실제 전송 순서를 관측한 결과가 아니다.

수신기를 준비할 때는 서명 검증, 이벤트 ID 중복 제거, 빠른 수신 응답 뒤 처리, 누락 보완을 설계한다. 공식 문서에는 재시도를 모두 소진하면 이벤트를 버리고, 비활성 endpoint에서 빠진 이벤트를 나중에 다시 보내지 않는다고 적혀 있다. 그러므로 웹훅만으로 완전한 상태 이력을 만들 수 있다고 가정하지 않는다. 전달·재시도 계약

서명 키를 교체하는 운영도 배포와 함께 준비해야 한다. API 참조는 교체 즉시 이전 키가 작동하지 않는다고 명시한다. 키 교체 완료와 수신기 설정 반영 사이에 틈이 생기지 않도록 담당자와 전환 순서를 정할 필요가 있다. 이 글에서는 키 생성·교체나 수신 서버를 실행하지 않았다. 서명 키 교체 계약

도입 전에 남길 한 장의 기록

가상 번역 서비스의 도입 검토는 다음처럼 짧게 적을 수 있다. 제품의 실제 응답이나 구현 완료를 나타내는 양식은 아니다.

고객 단위: 번역 앱 가입 사용자 / application
연결 책임: 가입 처리에서 저장, 요청 서버에서 인증 사용자와 대조
대상 경로: 즉시 번역 · 예약 번역 · 재시도 · 배치
배치 기준: 같은 고객끼리만 묶고 개별 결과까지 확인
상태 기록: 자사 이용 상태 / 공급자 상태 / 마지막 확인 시각
미확인 처리: 연결 또는 상태가 없으면 담당 확인 대상으로 구분
웹훅 조건: 현재 전송 미가동; 활성화 확인 전 자동 복구 의존 금지

여러 고객의 트래픽을 한 조직에서 보내는 서비스라면 먼저 귀속 누락이 생기는 경로부터 조사할 가치가 있다. 반면 자사 내부 업무만 호출하는 단순한 도구라면 고객별 프로필부터 추가할 이유가 약하다. 제품의 기능 개수보다 실제로 나눠야 할 이용 주체가 있는지를 먼저 묻자.

도입 평가에서도 “프로필 생성 성공률” 하나로 끝내지 않는다. 고객 ID가 빠진 전송 경로, 잘못 섞인 배치, 미확인 상태를 정상으로 표시한 화면, 상태 확인이 늦어져 멈춘 업무를 따로 본다. 이 글은 그 비율이나 개선 효과를 측정하지 않았다. 재사용할 것은 수치가 아니라 확인할 질문이다.

이벤트를 업무 처리와 연결하는 원리를 더 살펴보려면 트랜잭셔널 아웃박스와 중복 처리를 이어 읽을 수 있다. 공유 플랫폼의 배포 권한·소유자 책임이 궁금하다면 Void의 운영 경계가 다음 주제다. 이 점검표는 글 상단의 저장 기능으로 다시 찾고, 새 분석은 AI 시스템 주제 모음과 RSS에서 확인할 수 있다.