# Claude APIユーザープロファイルの設計と統制

> Claude APIのユーザープロファイルは、エンドカスタマー単位で制限やBANを閉じ込める仕組みです。ヘッダー付与、2種類のaccess_type、webhook監視の設計をまとめます。

- Canonical: https://kuucorp.com/blog/claude-user-profiles-end-customer-attribution-enforcement-design/
- Date: 2026-10-23
- Last modified: 2026-10-23
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
社内の複数事業部や取引先に Claude を再提供する LLM ゲートウェイを運用していると、ある1社の不正利用が組織全体の停止につながる懸念が残ります。Anthropic の安全分類器はAPIトラフィックを自動で監視しており、プロファイルが無ければ、エンドカスタマー1社が引き金となった制限が組織全体に及びます。2026年10月20日に提供が始まったユーザープロファイルは、この影響範囲を顧客単位に閉じ込めるための仕組みです。

ゲートウェイ全般の設計は[LLMゲートウェイのルーティングとレート制限](/blog/llm-gateway-routing-rate-limiting/)、観測側の統制は[OpenTelemetry出力の統制設計](/blog/claude-api-opentelemetry-export-destination-governance-design/)も参照してください。

## ユーザープロファイルとは何か

> ユーザープロファイルは、各リクエストがどのエンドカスタマー向けかを Anthropic に伝える仕組みで、課金対象外です。制限やBANを顧客単位に限定できます。

顧客ごとに `POST /v1/user_profiles` で1回登録し、返る `uprof_` 始まりのIDを保存します。以降、その顧客のための全リクエストに `anthropic-user-profile-id` ヘッダーを付けます。SDKでは `user_profile_id` 引数が同じ働きをします。トークン数計算、Message Batches、OpenAI SDK互換のリクエストでも同じヘッダーが使え、バッチでは全リクエストに適用されます。

プロファイルに会話内容は含まれません。送るのは名前、`reference_id`（自社の安定ID）、国などで、すべて任意です。Anthropic は内容を検証しません。氏名やメールを渡せない場合は、自社で計算した `name_hash` と `email_hash` を送れます。全プロファイルで同じ関数と正規化規則を使わないと照合されません。

## どの単位でプロファイルを切るべきか

> `access_type` は application と passthrough の2種類です。サービス利用者は1人1件、再販先の企業は1社1件で作成します。

| トラフィックの主体 | プロファイル | `access_type` |
|---|---|---|
| 自社製品のサインアップ済みユーザー | 1ユーザー1件 | `application`（既定） |
| API利用を再販する企業 | 1社1件（社員単位ではない） | `passthrough`（明示が必要） |
| 自社組織の内部利用 | 作らない | 該当なし |
| 自社組織内のワークスペース | 別プロファイルは不要 | 該当なし |

プロファイルはワークスペースではなく**組織**に属するため、IDは組織内のどのワークスペース経由でも使えます。公式は、エンドカスタマー向けトラフィックと自社の内部利用を別組織に分けるよう求めています。ワークスペース分離では足りません。`passthrough` で社員個人を特定できる場合は、Messages リクエストの `metadata.user_id` に個人の識別子を足します。

## プラットフォームごとの対応差をどう扱うか

> 作成できるのは Claude API、Claude Platform on AWS、Anthropic ホスト版の Microsoft Foundry です。Bedrock と Google Cloud は付与のみ可能です。

Claude in Amazon Bedrock では、IDをヘッダーではなくリクエスト本文の `user_profile_id` に入れます。Bedrock と Claude Models on Google Cloud（Google managed）は形式しか検査せず、実在を確認しません。成功レスポンスはプロファイルの一致を保証せず、**IDなしのリクエストは未帰属のまま通り**、制限が起きれば組織全体に及びます。ゲートウェイ側で「IDを持たない顧客向け呼び出しを拒否する」検査を入れてください。

AWS アカウントや Google Cloud プロジェクトは、Verification Portal で Anthropic 組織にリンクする手順が先に要ります。リンク後に表示が **Linked** になって初めて、プログラム承認が反映されます。

## 制限やBANをどう検知して運用に載せるか

> `enforcement_status` は unrestricted・restricted・banned の3値です。`user_profile.enforcement_action_opened` などのwebhook(beta)で検知します。

各プロファイルのレスポンスは `enforcement_status` と `enforcement_actions` を返します。アクションには `type`（`restriction` か `ban`）、`reason`、`opened_at`、`expires_at` があります。未知の値は安全側に倒し、`enforcement_status` は `restricted`、`reason` は `unspecified` として扱います。一覧は `enforcement_status[]` フィルターで絞れます。

組織 webhook はベータで、`webhooks-2026-10-07` ヘッダーが必要です。公式ドキュメントは、イベント配信がまだ稼働しておらず、登録しても何も届かないと注記しています。署名は Standard Webhooks 仕様で検証し、5秒以内に2xxを返します。重複は `webhook-id` で排除し、イベントは遅延や順序逆転があり得ます。到着順ではなくプロファイルの現在状態を信頼してください。

運用は次の形が堅実です。

1. 定期ジョブで `restricted` と `banned` を全ページ走査し、取りこぼしを補完する
2. 該当顧客のルーティングを止め、通知を出す
3. 解消後は新たに現在状態を取得してから再開する

プロファイル削除はIDの利用を止めてから行います。削除後およそ10分は、そのIDの推論が通る場合があります。なお Anthropic 側の trust and safety 記録は削除されません。

## 参考

- [User profiles for end-customer attribution — Claude Platform Docs](https://platform.claude.com/docs/en/manage-claude/user-profiles)
- [Organization webhooks — Claude Platform Docs](https://platform.claude.com/docs/en/manage-claude/organization-webhooks)
- [Claude Platform release notes — Claude Platform Docs](https://platform.claude.com/docs/en/release-notes/overview)

## まとめ

ユーザープロファイルは、再販や社内共有基盤で「1社の問題が全社停止になる」リスクを顧客単位に分割する仕組みです。顧客オンボーディングで登録し、全リクエストにIDを付け、`enforcement_status` を一覧走査とwebhookで監視します。マルチチーム・再販型のClaude基盤の設計は、[Kuuの大規模AI変革プログラム（RDE）](https://kuucorp.com/services/rde/)までご相談ください。
