エンド顧客のリクエストに ID を付けて Anthropic に伝える

公式の リリースノート の 2026 年 10 月 20 日の項目で、Claude API に user profiles が加わりました。エンド顧客ごとにプロファイルを作り、その顧客の代わりに送るリクエストへ ID を付けると、安全上の制限措置が組織全体ではなく 1 顧客に適用されうるようになります。翌 21 日の項目では、制限や停止の状態を見る enforcement_status と enforcement_actions が追加されました。

プラットフォームやゲートウェイを運営していたり、API の利用を再販していたりすると、エンド顧客のリクエストは自社の組織名義で届きます。公式によると、Anthropic は API のトラフィックに自動の安全性分類器をかけています。プロファイルが無いと、1 人の顧客が起こした措置は組織全体に及ぶ可能性があります。

この記事は、公式の User profiles と 組織 webhooks のドキュメントに基づきます。確認した日は 2026 年 10 月 25 日です。扱う範囲は、プロファイルの作り方、リクエストへの付け方、制限状態の確認方法、組織 webhooks の現状です。

API バージョン 2026-10-21 への移行は別の話題で、Claude API 2026-10-21 と SDK 更新 にまとめています。

誰がプロファイルを作るか

プロファイルが表すものは、Claude をどう売っているかで決まります。公式は、次の対応を示しています。

リクエストの持ち主プロファイルaccess_type
自社の製品にサインアップした利用者利用者ごとに 1 つ。サインアップ時に作るapplication (省略時の既定)
API の利用を再販する企業 (ゲートウェイ)企業ごとに 1 つ。企業内の人ごとには作らないpassthrough (既定ではないので送る)
自社の組織作らない該当なし
自社の組織の中のワークスペース別には作らない。ID はどのワークスペースでも使える該当なし

プロファイルは組織に属し、ワークスペースには属しません。

プロファイル ID の無いリクエストは、Anthropic が自社の利用として数えます。公式は、エンド顧客のトラフィックを送る組織と、自社の内部利用の組織を分けるよう求めています。ワークスペースを分けるだけでは足りません。プロファイルが組織に属するためです。

プロファイルは課金対象ではなく、料金にも影響しません。

プロファイルに入るのは、自社が送った情報と、Anthropic が設定するプログラムの状態・制限の状態だけです。会話の内容は入りません。Anthropic は送られた情報を、リクエストの帰属、不正利用の監視、利用ポリシーの執行、信頼できるアクセスのプログラムへの申請と利用に使い、内容の真偽は確かめないと公式は書いています。

プロファイルを作り、リクエストに付ける

作成は、顧客のオンボーディングの流れで 1 回だけ行います。次の例は、ゲートウェイ経由で API を買う企業を登録するもので、access_type に passthrough を指定しています。

curl https://api.anthropic.com/v1/user_profiles \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Acme Analytics, Inc.",
    "access_type": "passthrough",
    "external_user_details": {
      "reference_id": "cust-8f2a1c",
      "country": "US"
    }
  }'

返ってくる id は uprof_ で始まります。自社の顧客の記録に保存し、サービスの各インスタンスはそこから読みます。インスタンスごとに作り直してはいけません。POST /v1/user_profiles は冪等ではなく、reference_id が同じでも呼ぶたびに新しいプロファイルができます。

組織内のプロファイル数に上限はありませんが、作成にはレート制限があります。プロファイルの無い既存顧客をまとめて登録する前に、Anthropic の担当チームへ連絡するよう公式は求めています。

送る情報は、すべて任意です。使えるのは name、metadata、external_user_details の entity_type・country・reference_id・onboarded_at・account_status・name_hash・email_hash です。公式の指針は次のとおりです。

  • 分からない値は、仮の値を入れず省く。external_user_details の値は後から置き換えられるが、消せない
  • country には、自社ではなく顧客の国を入れる
  • reference_id には、自社の安定した識別子を入れる。一意でなくてもよい
  • 名前やメールアドレスを渡せないときは、name を省いて name_hash を、メールアドレスは email_hash を送る。ハッシュは自分で選んだ関数で計算し、全プロファイルで同じ関数と正規化にそろえる

作成には、Admin API キーは要りません。通常の API キーで呼べます。

付与は、顧客の代わりに送るすべてのリクエストに、anthropic-user-profile-id ヘッダーを付けて行います。SDK と CLI には、ヘッダーを代わりに送る引数があります。Python と TypeScript は user_profile_id、CLI は --user-profile-id です。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-user-profile-id: $PROFILE_ID" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

ヘッダーは、トークン数の計測、Message Batches、OpenAI SDK 互換のリクエストでも同じように使えます。バッチでは、バッチ内のすべてのリクエストに適用されます。

Claude API、Claude Platform on AWS、Anthropic がホストする Microsoft Foundry は、リクエストごとに ID を確かめます。形式が不正な場合や、自社の組織のものでない場合は、400 の invalid_request_error が返ります。既定では、ID が通るのはプロファイルを作った組織からのリクエストだけです。Claude API と Claude Platform on AWS の両方の組織でトラフィックを送っている場合、プロファイルを作っていない組織からのリクエストにも同じ 400 が返ります。

Message Batches だけは例外で、バッチの作成時には形式しか確かめません。ID が組織のものでなければバッチは作られ、中の各リクエストが errored になります。

FIXITFIXIT

プロファイルは、リクエストのたびに作るの？

DodaiDodai

違います。顧客ごとに 1 回だけ作り、ID を保存して使い回します。

FIXITFIXIT

ヘッダーを付け忘れたら、どうなるの？

DodaiDodai

自社の利用として扱われます。その分で措置が出ると、組織全体に及びます。

社内の人まで識別したいとき

passthrough のプロファイルが識別するのは企業で、リクエストを送った個人ではありません。1 人の特定できる人から来たリクエストなら、Messages のリクエスト自体の metadata.user_id に、その人の識別子を足せます。これはプロファイルの metadata とは別のものです。必須ではありませんが、個人による不正利用を Anthropic が見つけやすくなると公式は書いています。

Amazon Bedrock と Google Cloud 経由のとき

Claude in Amazon Bedrock と、Claude Models on Google Cloud (Google managed) でも、どちらの access_type のプロファイルも使えます。ただし、プロファイルの作成はできません。Claude API か Claude Platform on AWS の組織で作ります。以前の Bedrock の連携 (InvokeModel や Converse で呼ぶもの) では使えません。

ID の送り先は、プラットフォームで違います。

プラットフォーム作成ID の送り先
Claude APIできるanthropic-user-profile-id ヘッダー
Claude Platform on AWSできるanthropic-user-profile-id ヘッダー
Anthropic がホストする Microsoft Foundryできるanthropic-user-profile-id ヘッダー
Claude Models on Google Cloud (Google managed)できないanthropic-user-profile-id ヘッダー
Claude in Amazon Bedrockできないリクエスト本文の user_profile_id フィールド

Bedrock では、本文の最上位に user_profile_id を置きます。Bedrock と Google Cloud は、ID の形式しか確かめず、プロファイルを引きません。形式が正しければ何でも通るため、成功してもプロファイルと一致している証拠にはなりません。ID が無いリクエストはそのまま通り、措置が出れば組織全体に及びます。

なお、公式リリースノートの 10 月 22 日の項目で始まった Claude Models on Google Cloud (Anthropic managed) は、2026 年 10 月 25 日時点の User profiles のドキュメントに記載がありません。

また、プログラムの承認をプロファイルに反映するには、AWS アカウントや Google Cloud のプロジェクトを、Verification Portal で Anthropic の組織にリンクします。手順は公式のドキュメントにあります。

制限や停止を確認する

プロファイルを返すすべての応答に、enforcement_status と enforcement_actions が入ります。作成・取得・更新・一覧のいずれも同じです。リクエストの anthropic-beta ヘッダーに user-profiles-2026-09-04 以前の user-profiles- の値があると、この 2 つのフィールドは返らず、一覧の enforcement_status[] による絞り込みも 400 になります。この値を外して送ります。

enforcement_status は、開いている措置を 1 つの値にまとめたものです。User profiles のガイドは 3 つの値を挙げ、API リファレンスの List User Profiles は pending を加えた 4 つを挙げています。リファレンスでは、banned・pending・restricted・unrestricted の順に、最初に当てはまる値になります。

値意味
unrestricted開いている措置が無い
pending本人確認で解ける制限が開いていて、顧客が確認を出し、Anthropic の審査が終わっていない。理由が account_compromise の措置は開いていない
restricted措置が 1 つ以上開いていて、停止 (ban) は無い
banned停止が開いている

pending はリファレンスにだけある値です。

措置が開いている間、Anthropic はそのプロファイルの ID を付けた推論リクエストの一部または全部を拒否します。enforcement_actions は開いている措置の一覧で、無ければ空です。終わった措置は一覧から消えます。各措置には、次のフィールドがあります。

  • type: restriction または ban
  • id: enac_ で始まる措置の ID
  • reason: unsupported_region・fraud_or_abuse・high_harm・usage_policy_violation・account_compromise・unspecified のいずれか
  • action: 顧客が措置を解くためにできること。verify (顧客が本人確認を通せば解ける) か null。本人確認を出して審査を待つ間も null になる
  • opened_at: 措置が開いた時刻
  • expires_at: 措置が自然に終わる時刻。終わりの日が無ければ null。理由が account_compromise の措置では常に null

停止 (ban) では、action と expires_at は常に null です。

確認には、GET /v1/user_profiles/{id} でプロファイルを取得します。措置が開いているプロファイルを探すには、一覧を enforcement_status[]=restricted と enforcement_status[]=banned で絞り込みます。絞り込んだ一覧は、1 ページが limit より少なくても、0 件でも、続きがあることがあります。next_page が null になるまで取得します。一時的に措置を読めないプロファイルがあると、overloaded_error で失敗します。

Anthropic は、これらの値を増やすことがあります。公式は、未知の enforcement_status は restricted、未知の type は restriction、未知の reason は unspecified、未知の action は null として扱うよう示しています。この 2 つのフィールドは Anthropic が設定するため、作成や更新のリクエストに含めると 400 になります。external_user_details.account_status は自社が決めた状態の記録で、別のものです。

Claude Platform on AWS では、この 2 つのフィールドは措置を表しません。enforcement_status は常に unrestricted、enforcement_actions は常に空です。また、措置を理由にしたリクエストの拒否もありません。

注意

公式は、措置の変化があっても updated_at が変わるとは限らないと書いています。更新時刻の比較では検知できません。enforcement_status と enforcement_actions を、前回見た値と比べてください。

顧客が制限されたときにやること

公式のドキュメントから読み取れる対応は、次の範囲です。

  • action が verify なら、顧客が本人確認を通せば措置が解けます。顧客に本人確認を案内します
  • 自社の判断でも顧客のアカウントを止めるなら、external_user_details.account_status を更新します。公式の更新例では suspended を送っています
  • action が null の措置は、いま顧客の側で解く手段がありません。停止 (ban) は常にこれにあたります

組織 webhooks｜現時点ではイベントが届かない

公式リリースノートの同じ 10 月 20 日の項目で、Admin API に組織 webhooks も加わりました。beta で、webhooks-2026-10-07 の beta ヘッダーを付けて使います。エンドポイントは /v1/organizations/webhooks で、受け取れるイベントは 2 種類です。

イベント起きること
user_profile.enforcement_action_openedAnthropic が、組織のプロファイルに措置を開いた
user_profile.enforcement_action_resolved措置が終わった。Anthropic が解いた場合と、expires_at を過ぎた場合

利用には、Anthropic の担当チームへの申請が必要です。HIPAA readiness を有効にした組織では使えません。認証には、Admin API キー、org:admin スコープの OAuth トークン、ワークスペースに限定されない個人用またはサービスアカウントのキーのいずれかを使います。エンドポイントの一覧と参照は組織のメンバーなら誰でもできますが、作成・変更・削除と署名シークレットの再生成は、admin・owner・primary owner のロールに限られます。

公式のドキュメントには、次の注記があります。

Event delivery isn't live: Anthropic doesn't send the two events, so an endpoint you register receives nothing.

つまり、2026 年 10 月 25 日に確認した時点では、エンドポイントを登録しても何も届きません。登録と受信側の実装は進められますが、検知の手段としては使えません。当面は、前の節のプロファイルの取得と一覧で、自社から確認することになります。

受信側を作るときの要点は、公式ドキュメントに次のように書かれています。

  • 配信は Standard Webhooks の仕様に従い、webhook-id・webhook-timestamp・webhook-signature のヘッダーが付く。署名は、エンドポイントの署名シークレットで確かめてから信用する
  • 5 秒以内に 2xx を返し、重い処理は後で行う
  • 同じイベントが複数回届くことがある。イベントの id で重複を除く
  • 配信に失敗すると、Anthropic は数分のうちに何度か再試行する。すべて失敗すると、そのイベントは破棄される。取りこぼした分は、措置の状態で絞り込んだ一覧で拾う
  • イベントの中身は ID だけで、措置の内容やプロファイルは含まない。data.id のプロファイルを取得して現在の状態を見る
  • 順序は保証されない。届いた順ではなく、取得したプロファイルの現在の状態を使う
  • エンドポイントは HTTPS の 443 番ポートで、IP アドレスでなく公開のドメイン名にする。1 組織で 32 個まで
  • リダイレクト (3xx) を返す、URL が非公開の IP に解決される、配信の失敗が続く場合、Anthropic はエンドポイントを無効にする。無効の間のイベントは、後からも送られない

署名シークレット (whsec_ で始まる) は、エンドポイントの作成時と再生成時の応答にだけ含まれます。保管の方法を先に決めておきます。

配信が始まっても、イベントが来ない措置があります。プロファイルの削除で閉じた措置には、user_profile.enforcement_action_resolved イベントが出ません。組織への配信が有効になる前や、エンドポイントを登録する前に開いた措置には、user_profile.enforcement_action_opened イベントが来ません。後者の措置もプロファイルには表示されるので、一覧の絞り込みで見つけます。

FIXITFIXIT

webhook を登録しておけば、制限されたときに通知が来るんだよね？

DodaiDodai

今は来ません。公式が、イベント配信は始まっていないと書いています。

FIXITFIXIT

じゃあ、気づく手段は何もないの？

DodaiDodai

プロファイルの取得と一覧があります。定期的に確認する処理を先に作ります。

プロファイルの更新と削除

顧客の情報や状態が変わったら、POST /v1/user_profiles/{id} で更新します。送ったフィールドだけが変わります。name と access_type は置き換わり、external_user_details の各フィールドも置き換わります。値は消せず、null を送ると 400 になります。metadata はキーごとに統合され、空文字列を送るとそのキーが消えます。

顧客がアカウントを閉じたり、データの削除を求めたりしたときは、DELETE /v1/user_profiles/{id} で削除します。プロファイルと、自社が送った name・external_user_details・metadata が消えます。Anthropic が保管する、そのプロファイル ID についての安全性に関する記録は消えません。

削除の前に、その顧客のリクエストへ ID を付けるのをやめます。削除のあとは、プロファイルの各エンドポイントが 404 を返します。約 10 分間は、その ID を付けた推論リクエストが成功することがあります。その後は、ID を毎回確かめるプラットフォームで 400 になります。Bedrock と Google Cloud はプロファイルを引かないので、受け付け続けます。削除後も顧客を続けて受け入れるなら、新しいプロファイルを作り、ID を切り替えてから古いほうを消します。

削除が 5xx で失敗したら再試行します。再試行で 404 が返れば、最初の削除は通っています。

FIXIT の受け止め

私たちは、エンド顧客向けに Claude API を使うサービスでは、この仕組みを使う前に「誰のリクエストを誰の ID で送るか」を決めておくのが先だと考えています。決まっていないと、ID の付け忘れが出た経路だけ、自社の利用として扱われます。

プロファイルの作成にはレート制限があり、プロファイルの無い既存顧客は、後からまとめて登録することになります。その前には Anthropic の担当チームへの連絡も要ります。顧客のオンボーディングにプロファイルの作成を最初から組み込んでおけば、この一括登録を抱えずに済みます。モデルや SDK の更新に追随する確認項目は、Claude API 2026-10-21 と SDK 更新 でも同じ見方で整理しています。

まず自社のトラフィックを分ける

最初に確かめるのは、自社の Claude API の組織に、エンド顧客のトラフィックと自社の内部利用が混ざっていないかです。混ざっているなら、組織を分けるところから始めます。そのうえで、顧客のオンボーディングにプロファイルの作成を足し、顧客のリクエストへ anthropic-user-profile-id を付けます。

Claude API を組み込んだサービスの運用設計は AI 開発ツール定着支援 で、AI を組み込んだプロダクト開発そのものは AI 駆動開発 でお手伝いしています。個別のご相談は お問い合わせ から承っています。