ClaudeのVerification Portalリンクをaction_urlsで発行する手順

Claude APIを組み込んだサービスで、顧客の組織が受けた承認を自社経由のリクエストにも効かせるには、顧客自身が「ユーザープロファイル」を自分のAnthropic組織に紐づける必要があります。その入口になるのが、POST /v1/user_profiles/{id}/action_urls で発行する登録リンクです。

リンクを作るのは自社、紐づけを承認するのは顧客という分担になります。この記事では、リンクの発行から顧客側の画面、紐づけ後の確認、そして組織で機能が有効でないときの404までを順に並べます。

登録リンクが必要になる場面

プロファイルは、自社が各リクエストをどの顧客のためのものとして送っているかをAnthropicに伝える仕組みです。顧客ごとに作成し、リクエストのたびに uprof_ で始まるIDを付けます。作成からヘッダーの付け方まではClaude APIのUser Profilesでエンドユーザーを識別する手順で扱っています。

Anthropicは、組織が申請できる承認プログラムをVerification Portalで運用しています。顧客が承認を受けても、それだけでは自社経由のリクエストには効きません。顧客がプロファイルを自組織に紐づけて初めて、承認済みのプログラムがプロファイルIDつきのリクエストに適用されます。

Cyber Verification Programの申請そのものは申請手順に、ワークスペースへの割り当てはConsole管理者向けの手順にあります。それらは顧客の組織が承認を受ける側の話で、このリンクは、その承認を自社がプロファイル単位で作ったリクエストにつなげる役目です。

単に帰属を伝えたいだけなら、このページの手順は要りません。リンクの発行が組織で有効になっていない場合も同じです。

リンクを発行するAPI

リンクの発行は、対象プロファイルのIDをパスに入れた action_urls へのPOSTです。本文で action.type を enroll_end_user にします。

curl https://api.anthropic.com/v1/user_profiles/uprof_011CZkZCu8hGbp5mYRQgUmz9/action_urls \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"action": {"type": "enroll_end_user"}}'

レスポンスには、リンクと失効時刻が入ります。

{
  "type": "user_profile_action_url",
  "url": "https://portal.anthropic.com/enroll?enrollment_token=...",
  "expires_at": "2026-03-15T11:00:00Z"
}

SDKでも同じ呼び出しができます。PythonではIDと action を渡し、返ってきたオブジェクトの url を使います。

client = anthropic.Anthropic()
 
action_url = client.user_profiles.action_urls.create(
    "uprof_011CZkZCu8hGbp5mYRQgUmz9",
    action={"type": "enroll_end_user"},
)
 
print(action_url.url)

TypeScript、C#、Go、Java、PHP、Rubyのほか、ant user-profiles:action-urls create というCLIにも同じ操作があります。プロファイルがまだ無いときは、先に作成しておく必要があります。

404が返ったとき:プロファイル不明と同じ見た目

組織でこの機能が有効でないと、action_urls は404を返します。厄介なのは、存在しないプロファイルIDを指定したときも同じ404になる点です。ステータスだけでは原因を区別できません。

先にIDを疑うのは、取り違えのほうが起きやすいからです。取得に成功するIDで404が続くときに限って、機能が有効かどうかを疑います。

リンクの有効期限と扱い方

リンクは expires_at まで使えます。目安は発行から約1時間です。

• 顧客がリンクを求めた瞬間に発行する。たとえば自社の画面でボタンが押されたとき
• 事前に発行してメールに書いておく運用は避ける。読まれたときには失効している
• 顧客は期限内なら同じリンクを何度でも開ける
• 期限切れなら再発行する。呼ぶたびに新しいリンクが返る
• 新しいリンクを作っても、以前のリンクは取り消されない

最後の点は見落としやすいところです。再発行で古いリンクが無効になるわけではないので、誤送信したリンクを「作り直して上書きする」ことはできません。

リンクを持っている人は、期限まで誰でも使えます。渡す相手は、そのリンクの対象である顧客本人に限ります。宛先は、顧客のAnthropic組織のadminかownerです。adminかownerだけがプロファイルを紐づけられるためです。

URLの形式は変わる可能性があるため、中身を解析したり、自前で組み立てたりしないでください。受け取った文字列を、そのまま顧客に渡します。

利用経路による違い

action_urls が使えるかどうかは、Claudeを使う経路で変わります。

AWS上のClaude Platformでは、別のパスを使います。リクエストに本文はなく、レスポンスの url と expires_at はClaude APIの場合と同じです。SDKとCLIではbetaの名前空間にあり、Pythonなら client.beta.user_profiles.create_enrollment_url() です。

enrollment_url はベータヘッダー付きのエンドポイントとして、User Profilesの解説記事でも触れています。ベータでない action_urls が別に用意されているため、Claude APIの組織ではこちらを使います。

顧客の側で起きること

リンクは portal.anthropic.com のVerification Portalを開きます。ログイン後、ポータルには自社のAnthropic組織名とプロファイルのIDが表示されます。

自社の画面から顧客を送り出すときは、この3段階を前提に説明を添えておくと、顧客が途中で止まりにくくなります。特に「adminかownerが開く必要がある」ことは、リンクを渡す画面に書いておく価値があります。

紐づけが進まない3つのパターン

画面に出る文言ごとに、原因と次の手が決まっています。

プロファイルが紐づけられるのは1つの組織だけです。顧客が組織を取り違えて紐づけてしまったときも、この解除の手順で戻します。

紐づけのあとに自社がすること

ポータルは顧客を自社の製品に戻しません。Anthropicから自社へ通知が届くこともありません。完了したら戻ってくるよう、自社の画面で顧客に伝える必要があります。

紐づけ自体が承認を意味するわけではない点にも注意してください。紐づけは、プロファイルと顧客の組織をつなぐだけです。顧客の組織が承認を受けているプログラムは、プロファイルIDつきのリクエストに適用されるようになります。例外はCyber Verification Programのアクセスレベル(制度の拡大と審査段階)で、これは顧客がポータルで、紐づけたプロファイルごとに有効化します。プロファイル側には、紐づけ済みかどうかを示すフィールドがありません。

programsで適用状況を読む

適用状況は、プロファイルを取得して programs を読むことで確かめられます。cyber や efs のようなプログラム名がキーになっており、すべてのプロファイルにすべてのキーが存在します。値は次のどれかです。

取得したレスポンスから、顧客に見せる状態を決める処理の例です。公式の例ではなく、programs の仕様から組み立てた書き方です。

def program_state(programs: dict, name: str) -> str:
    entry = programs.get(name)
    if entry is None:
        return "no-status"      # null: 報告できる状態がない
    return entry["status"]      # active / pending / rejected
 
# 例: cyber が pending なら「審査中」と表示する

null は「報告できる状態がない」という意味で、紐づけの有無を示す値ではありません。プロファイルに紐づけ済みかどうかは programs からは判定できないため、自社の記録として、顧客が完了を申告した事実を持っておきます。

顧客が「完了しました」と戻ってきた時点でプロファイルを取得し直します。通知は来ないので、状態を知る手段はこれだけです。

BedrockとGoogle Cloudでは、自社側のアカウントも紐づける

推論をClaude in Amazon BedrockやClaude Models on Google Cloud(Google managed)で動かしている場合は、顧客のプロファイルとは別に、自社のアカウントも紐づけが要ります。プログラムがAWSアカウントやGoogle Cloudプロジェクトからのリクエストに適用されるのは、そのアカウントを、プロファイルを作成しているAnthropic組織に紐づけたあとです。

手順は3段階です。

1. プロファイルを作成している組織のadminかownerが、ポータルのLinked accountsで紐づけを始める
2. AWSアカウントまたはGoogle CloudプロジェクトのIAMを管理できる人が、ポータルの表示するコマンドを実行する
3. adminかownerが、ポータルで検証を完了する

ポータルでLinkedと表示されるまでは適用されません。顧客の紐づけが終わっていても、自社のアカウントが未紐づけなら、承認は自社経由のリクエストに効きません。

BedrockとGoogle Cloudは、IDの形式だけを検査して、プロファイルの存在は照会しません。形式が不正なら400、形式が正しければ成功を返します。成功したからといって、プロファイルが実在する証拠にはなりません。

実装時の落とし穴

ほかにも押さえておきたい点があります。

• 開く人がadminかownerでなければ紐づけられない。リンクを渡す画面でその旨を書いておく
• 紐づけ後にAnthropicから通知は来ない。戻ってもらう導線を自社の画面に作る
• 紐づけは承認ではない。承認の有無は programs の status で読む

まとめ

自社が担うのは、プロファイルの作成、顧客が求めた瞬間のリンク発行、そして顧客をadminかownerの手元へ導くところまでです。紐づけの承認は顧客が行い、完了通知は来ません。完了後の確認は programs の取得で行います。

経路ごとに入口が違うため、実装の最初に、自社の推論がClaude API、AWS上のClaude Platform、Foundry、Bedrock、Google Cloudのどこで動くかを確定させると、使うエンドポイントが決まります。Claude APIなら action_urls、AWS上のClaude Platformなら enrollment_url、Foundryならこのエンドポイントは使えません。