---
title: Linked billing
url: https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections
description: 顧客がOAuthを使用して自身のClaude Platform組織をアプリにリンクできるようにし、Claudeの使用量を顧客の組織に請求します。
---

<Warning>
  Claude Platform OAuthはBeta Serviceです。これは、[商用利用規約](https://www.anthropic.com/legal/commercial-terms)や[サービス固有の規約](https://www.anthropic.com/legal/service-specific-terms)など、Anthropicとの契約に基づいて提供されるリリース前のソフトウェアです。エンドポイント、パラメータ、および動作はベータ期間中に変更される可能性があります。本番環境での使用には適さない場合があります。
</Warning>

Linked billingを使用すると、顧客は自身のClaude組織を通じて、アプリ内でのClaudeの使用量を支払うことができます。顧客は自身のClaude組織をアプリに一度リンクします。APIではこのリンクを「connection」（接続）と呼びます。顧客がリンクした後は、各Claude APIリクエストごとに、顧客とあなたのどちらが支払うかを選択します。顧客はいつでもアプリのリンクを解除できます。顧客への請求を指定したリクエストを顧客に請求できない場合、Claude APIはあなたに請求するのではなく、そのリクエストを拒否します。

このガイドは、アプリのユーザーが主にClaude Platformの顧客である開発者を対象としています。アプリに「Link your Claude organization」ボタンを追加します。ユーザーがそれをクリックし、Claudeにサインインして、顧客の指示によってあなたが行うClaude APIリクエストの料金を、アプリがそのユーザーのClaude組織に請求することを承認します。その後、アプリは顧客が支払うリクエストに[`billing_policy`](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#step-3-update-calls-to-claude)フィールドを追加します。

## 対象となる顧客とエンドポイント

**対象となる顧客：** この方法で請求できるのは、顧客のClaude Platform組織がAPI使用量の料金をAnthropicに直接支払っている場合のみです。前払いクレジットと請求書払いのどちらも対象となります。クラウドマーケットプレイス（AWS、Google Cloud、またはAzure）を通じて請求される組織は、この統合を通じて請求できません。Claudeのサブスクリプションプランのみを利用している組織も同様です。それらの組織向けのリクエストは403 `user_profile_not_billable`で拒否されます。

リクエストはあなたの組織内で実行されるため、あなたのレート制限、モデルへのアクセス、サービスティア、データ保持、および暗号化キーが適用されます。これらのリクエストには、[「zero data retention」（ゼロデータ保持）、すなわちZDR](https://platform.claude.com/docs/ja/manage-claude/api-and-data-retention#zero-data-retention-zdr-scope)、「business associate agreement」（事業提携契約）、すなわちBAA、「customer-managed encryption keys」（カスタマー管理の暗号化キー）、すなわちCMEKなど、顧客自身のデータに関する取り決めは適用されません。この使用量についてHIPAA、FERPA、またはCMEKによる保護を必要とする顧客はリンクしないでください。

**サポートされているエンドポイント：** `billing_policy`は以下でサポートされています：

* `/v1/messages`
  * 既知の制限：顧客に請求するリクエスト（`bill_to: "user_profile"`）では、[課金対象のコード実行機能](https://platform.claude.com/docs/ja/about-claude/pricing#code-execution-tool)を使用できません（APIは400を返します）。そのため、これらのリクエストは`bill_to: "self"`を指定するか、`billing_policy`なしで送信してください。
* `/v1/chat/completions`
* `/v1/messages/count_tokens`は`billing_policy`フィールドを受け付けますが無視するため、送信しようとしているのとまったく同じボディでトークン数をカウントできます。

[Message Batches](https://platform.claude.com/docs/ja/build-with-claude/batch-processing)（`/v1/messages/batches`）は、現在、顧客への請求に対応していません。バッチ内のリクエストは `bill_to: "self"` を指定するか、`billing_policy` を指定せずに送信してください。そうすれば、通常どおりあなたに請求されます。バッチ内で `bill_to: "user_profile"` を設定したリクエストは拒否されます。その結果は `invalid_request_error` を伴う `errored` となり、あなたにも顧客にも請求されず、バッチ内の他のリクエストは通常どおり実行されます。

他のエンドポイントでのサポートを希望する場合は、Anthropicのアカウントチームにお問い合わせください。

### 支払いに使用できるクレジット

プラットフォームが顧客に請求するリクエストの支払いには、すべてのクレジットを使用できるわけではありません。支払いに使用できるものは、請求先の組織によって異なります。あなたが顧客に請求する場合は顧客、プラットフォームがあなたに請求する場合はあなたの組織が請求先となります。

その組織のためにClaude Consoleで購入したクレジットは、これらのリクエストの支払いに使用できます。その組織が請求書払いの場合は、これらのリクエストの料金が請求書で請求されます。

Anthropicからの一部のプロモーションクレジットは、これらのリクエストの支払いに使用できません。これには、Claude Max、Ultra、およびTeamプランに付属する月間APIクレジットが含まれます。Anthropicのパートナー、VC、およびスタートアップ向けプログラムのクレジットは、これらのリクエストの支払いの対象外です。

その組織のアカウントにリクエストの支払いに使用できるものが何もない場合、Claude APIはそのリクエストを402で拒否することがあります。レスポンスには、拒否の原因がクレジット不足なのか支出制限なのかは示されません。[想定されるエラー](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#expected-errors)を参照してください。

## セットアッププロセス

以下の3つのステップは一度だけ行います。これらのステップでアプリをAnthropicに登録します。その後の[リンクするユーザープロファイル](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#which-user-profile-to-link)では、ユーザープロファイルを作成する前に把握しておく必要があるルールについて説明します。

### ステップ1：アプリを作成する

Claude ConsoleでOAuthアプリを作成します。これはあなたの製品をAnthropicに対して識別する登録情報です。リダイレクトURIをクライアントIDに紐付け、その名前がユーザーの承認ページに表示されます。

管理者ロールを持つ組織のメンバーが、Consoleの[OAuthアプリ](https://platform.claude.com/settings/oauth-apps)ページを開き、**作成**をクリックします。アプリの名前とリダイレクトURI（承認後にブラウザが戻る、アプリ内のアドレス）を入力します。**What the app can do**で、**Bill and link to organizations**を選択します。

新しいアプリのページが開きます。Consoleに表示されるアプリのクライアントIDをコピーします。アプリは、ステップ5で承認ページをリクエストするとき、ステップ6でブラウザをリダイレクトするとき、ステップ8でコードを交換するときにこれを送信し、どのアプリからのリクエストかをAnthropicが識別できるようにします。クライアントIDは公開情報です。**外観**タブで、アプリの名前、ホームページ、ロゴURLを設定します。

**設定**タブでは、新しいアプリはテスト中の状態で始まるため、**Who can link**は**Test users only**と表示されます。[アプリを公開](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#publish-your-app)して本番稼働すると、この設定は**Any Claude user**と表示されます。

<Note>
  組織は複数のOAuthアプリを登録できます。たとえば、本番用に1つ、テスト用に1つといった形です。各アプリには独自の接続があります。テストアプリをリンクした顧客は、本番アプリにはリンクされていません。統合を運用する期間を通じて、Linked billingは1つの本番アプリで使用してください。
</Note>

### ステップ2：クライアント認証を設定する

バックエンドが`auth.claude.com`に対して、そのリクエストがあなたのアプリから送信されたものであることを証明する方法を設定します。これはクライアントシークレットの代わりとなります。AnthropicはOAuthアプリに対してクライアントシークレットを発行しません。

アプリの**Client authentication**タブで、**ID プロバイダー**（バックエンドのトークンに署名する発行者）を選択します。追加するには、**Register a new issuer**をクリックします。次に、それらのトークンが一致する必要がある**サブジェクトパターン**、または**詳細な一致オプション**の下のクレーム条件を設定します。保存すると、タブに期待されるオーディエンスが表示されます。クライアントアサーションの`aud`クレームは、その値と完全に一致する必要があります。

<Note>
  アプリは、`private_key_jwt`方式（RFC 7523）のバリエーションを使用して、PARエンドポイント、トークンエンドポイント、および取り消しエンドポイントに対して認証します。各リクエストで、バックエンドは「client assertion」（クライアントアサーション）、つまりアイデンティティプロバイダーが発行するJWTを送信します。`auth.claude.com`は、その発行者に登録されたキーでトークンの署名を検証し、ここで設定したサブジェクトまたはクレーム条件と照合します。クライアントアサーションに含める必要があるクレームについては、[クライアントアサーションのクレーム](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/oauth-reference#client-assertion-claims)を参照してください。
</Note>

### ステップ3：バックエンドのアイデンティティを設定する

バックエンドがClaude APIを呼び出すには、独自のアイデンティティが必要です。次の2つを作成します：

* **「service account」（サービスアカウント）。** これは、Claude組織内の人間以外のアカウントです。バックエンドはClaude APIを呼び出す際に、このアカウントとして認証します。
* **2つ目のフェデレーションルール。** ステップ2のアプリのクライアント認証用のルールと同様に、バックエンドが独自のアイデンティティプロバイダーからのトークンで認証できるようにします。

Claude Consoleでこれらを設定するには、[Workload Identity Federation](https://platform.claude.com/docs/ja/manage-claude/workload-identity-federation)ガイドに従ってください。

次に、アプリの**Client authentication**タブで、そのサービスアカウントをアプリのオペレーターサービスアカウントとして選択します。推論リクエストを送信し、リンクされたユーザープロファイルに請求を帰属させることが許可されているのは、そのサービスアカウントのみです。1つのサービスアカウントがオペレーターになれるのは、1つのOAuthアプリのみです。

デフォルトでは、そのサービスアカウントとして認証された任意のリクエストが、Messages APIでユーザープロファイルヘッダーと`bill_to`を設定することで、リンク済みのすべての顧客に請求できます。特定の接続のみに制限された認証トークンを取得するには、[接続ごとのOAuthトークン](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection)を参照してください。顧客をリンクする前に、アプリの[ワークスペースを設定](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens)してください。ステップ8では顧客ごとにこのようなトークンが返されますが、そのためにはアプリで、推論を実行する組織内のデフォルトのワークスペースを指定する必要があります。接続ごとの「refresh token」（リフレッシュトークン）が必要な場合は、アプリの**Offline access**も有効にしてください。その後、顧客をリンクする前に、ステップ5の認可フローで`offline_access`をリクエストしてください。

### リンクするユーザープロファイル

「user profile」（ユーザープロファイル）は、あなたの顧客の1人を表す、あなた自身のClaude組織内のレコードです。顧客に請求する各リクエストにはプロファイルのIDが含まれるため、Anthropicはどの顧客に請求するかを識別できます。プロファイルのその他の機能については、[エンドカスタマーへの帰属のためのユーザープロファイル](https://platform.claude.com/docs/ja/manage-claude/user-profiles)を参照してください。

最初の顧客をリンクする前に、各顧客をどのユーザープロファイルで表すかを決めておいてください。1つのアプリ内では、接続は1対1です：

* 顧客のClaude組織は、あなたのユーザープロファイルのうち1つにのみリンクできます。
* ユーザープロファイルは、1つのClaude組織にのみリンクできます。

顧客のClaude組織とは、ユーザーがアプリを承認する際に選択する組織です。顧客のチームがClaude組織をどのように使用しているかは、顧客に尋ねてください。1対1のルールを顧客レコードに適用するには：

* **1つの顧客の複数のチームが1つのClaude組織を共有している場合：** すべてのチームに1つのユーザープロファイルを使用してください。
* **各チームが独自のClaude組織を持っている場合：** 組織ごとにユーザープロファイルを作成してください。

1対1のルールの範囲内で、あなたの組織内の任意のアクティブなユーザープロファイルをリンクできます。リンクによって、プロファイル、そのID、またはその使用履歴が変更されることはありません。すでにリンク済みのClaude組織に2つ目のユーザープロファイルをリンクすると、承認は拒否されます。[`user_profile_already_linked`](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#user-profile-already-linked)を参照してください。

#### 個人ごとのユーザープロファイル

製品を使用する各個人のユーザープロファイルをすでに作成している場合があります。そのうちの複数の人が同じ顧客のために働いている場合もあります。その場合、Anthropicは、顧客のClaude組織用にもう1つユーザープロファイルを作成し、そのプロファイルをリンクすることを推奨します。

送信するプロファイルIDは、リクエストの支払者によって異なります：

* **顧客に請求するリクエスト：** 顧客のプロファイルのIDを送信します。`/v1/messages`リクエストで個人も識別するには、[`metadata.user_id`](https://platform.claude.com/docs/ja/api/messages/create)をその人の識別子に設定します。この識別子は任意であり、Anthropicが1人の人物による不正使用を検出するのに役立ちます。名前、メールアドレス、電話番号ではなく、不透明な値を使用してください。
* **あなたが支払うリクエスト：** 引き続きその人自身のプロファイルIDを送信できます。

## 各顧客をリンクする

ステップ4から8は、組織をリンクする顧客ごとに行います。以下のPythonコードスニペットには、Anthropic SDKといくつかの標準インポートが必要です。[コードスニペットの初期化](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#code-snippet-initialization)を参照してください。他の言語の例とCLIは、環境から認証情報を取得します。アプリはWorkload Identity Federationで認証する必要があるため、`ANTHROPIC_API_KEY`が設定されていないことを確認してください。

製品内で顧客が請求や統合を管理する場所に「Link your Claude organization」ボタンを追加します（ボタンのHTML、色、ロゴについては、[ブランディングサンプル](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/branding-samples#buttons)を参照してください）。リンクするには、Claude組織の管理者または請求のロールを持っている必要があることを顧客に伝えてください。

まず自分で手順を試すには、[顧客としてテストする](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#test-as-a-customer)を参照してください。

<Frame>
  ![ステップ5から8のシーケンス図：承認リクエスト、ユーザーの承認、接続IDへの交換](https://platform.claude.com/docs/ja/images/oauth-apps-billing-connection-flow.svg)
</Frame>

### ステップ4：顧客のユーザープロファイルを作成する

顧客のClaude組織ごとに1つのユーザープロファイルを作成し、そのプロファイルのIDを製品内の顧客レコードに保存します。

この顧客のClaude組織用のユーザープロファイルがすでにある場合は、このステップをスキップし、そのプロファイルのIDを使用してください。それがどのプロファイルかを判断するには、[リンクするユーザープロファイル](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#which-user-profile-to-link)を参照してください。

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/user_profiles \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "name": "Example Customer Inc.",
      "external_user_details": {"reference_id": "your-customer-id-123"}
    }'
  ```

  ```bash CLI
  ant user-profiles create \
    --name "Example Customer Inc." \
    --external-user-details.reference-id your-customer-id-123
  ```

  ```python Python
  def create_user_profile(name: str, customer_id: str) -> str:
      profile = client.user_profiles.create(
          name=name,
          external_user_details={"reference_id": customer_id},
      )
      return profile.id  # "uprof_..."


  user_profile_id = create_user_profile("Example Customer Inc.", "your-customer-id-123")
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const profile = await client.userProfiles.create({
    name: "Example Customer Inc.",
    external_user_details: { reference_id: "your-customer-id-123" }
  });

  console.log(profile.id); // "uprof_..."
  ```

  ```csharp C#
  AnthropicClient client = new();

  var profile = await client.UserProfiles.Create(
      new()
      {
          Name = "Example Customer Inc.",
          ExternalUserDetails = new() { ReferenceID = "your-customer-id-123" },
      }
  );

  Console.WriteLine(profile.ID);
  ```

  ```go Go
  client := anthropic.NewClient()

  profile, err := client.UserProfiles.New(context.Background(), anthropic.UserProfileNewParams{
  	Name: anthropic.String("Example Customer Inc."),
  	ExternalUserDetails: anthropic.UserProfileExternalUserDetailsParams{
  		ReferenceID: anthropic.String("your-customer-id-123"),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(profile.ID)
  ```

  ```java Java
  import com.anthropic.models.userprofiles.UserProfileCreateParams;
  import com.anthropic.models.userprofiles.UserProfileExternalUserDetailsParams;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = UserProfileCreateParams.builder()
          .name("Example Customer Inc.")
          .externalUserDetails(UserProfileExternalUserDetailsParams.builder()
              .referenceId("your-customer-id-123")
              .build())
          .build();
      var profile = client.userProfiles().create(params);

      IO.println(profile.id());
  }
  ```

  ```php PHP
  $client = new Client();

  $profile = $client->userProfiles->create(
      name: 'Example Customer Inc.',
      externalUserDetails: ['referenceID' => 'your-customer-id-123'],
  );

  echo $profile->id, PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  profile = client.user_profiles.create(
    name: "Example Customer Inc.",
    external_user_details: { reference_id: "your-customer-id-123" }
  )

  puts(profile.id)
  ```
</CodeGroup>

あなたの組織がAPIアクセスを再販している場合は、このプロファイルを作成する際に`"access_type": "passthrough"`も送信してください。これらのサンプルでは`access_type`を省略しているため、`application`プロファイルが作成されます。2つのタイプについては、[プロファイルを付与する対象を決める](https://platform.claude.com/docs/ja/manage-claude/user-profiles#decide-who-gets-a-profile)を参照してください。

レスポンスにはプロファイルの`id`（例：`uprof_01HV9Z`）が含まれます。

<Note>
  作成リクエストは、同じ`reference_id`（顧客に対するあなた独自のID）であっても、毎回新しいプロファイルを作成します。そのため、接続を試みるたびにプロファイルを作成するのではなく、保存したIDを再利用してください。
</Note>

### ステップ5：プッシュ型認可リクエストURLを作成する

ステップ4の顧客のユーザープロファイルを参照する「pushed authorization request」（プッシュ型認可リクエスト）を作成します。レスポンスで`request_uri`が返されます。次のステップでは、これを使用してユーザーを承認ページにリダイレクトします。

リクエストを送信する前に、バックエンドは2つのランダムな値を作成し、ブラウザセッションと顧客レコードに関連付けて保存します。どちらもステップ8で再度使用します：

* `state`値。アプリに戻ってきたブラウザが、このリクエストを開始したブラウザと同じであることを確認するために使用します。
* PKCEコードベリファイア。バックエンドだけが知っているシークレットです。リクエストにはそのハッシュ（コードチャレンジ）が含まれ、ステップ8ではベリファイア自体を送信するため、返されたコードを使用できるのはバックエンドだけになります。

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/par \
    -H "content-type: application/json" \
    -d '{
      "response_type": "code",
      "client_id": "YOUR_CLIENT_ID",
      "redirect_uri": "https://app.example.com/claude/billing/callback",
      "scope": "billing:attribution",
      "connection_type": "organization_shared",
      "connection_auth_target": "platform",
      "user_profile_id": "uprof_01HV9Z",
      "state": "RANDOM_STATE",
      "code_challenge": "BASE64URL_SHA256_OF_VERIFIER",
      "code_challenge_method": "S256",
      "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
    }'
  ```

  ```python Python
  def push_authorization_request(user_profile_id: str) -> dict:
      state = secrets.token_urlsafe(32)
      code_verifier = secrets.token_urlsafe(64)
      code_challenge = create_s256_code_challenge(code_verifier)

      response = httpx.post(
          f"{AUTH}/v1/oauth/par",
          json={
              "response_type": "code",
              "client_id": CLIENT_ID,
              "redirect_uri": REDIRECT_URI,
              "scope": "billing:attribution",
              "connection_type": "organization_shared",
              "connection_auth_target": "platform",
              "user_profile_id": user_profile_id,
              "state": state,
              "code_challenge": code_challenge,
              "code_challenge_method": "S256",
              "client_assertion_type": JWT_BEARER,
              "client_assertion": client_assertion(),
          },
      )
      response.raise_for_status()  # on an error, do not redirect the browser

      return {
          "state": state,
          "code_verifier": code_verifier,
          "request_uri": response.json()["request_uri"],  # valid for 600 seconds
          "user_profile_id": user_profile_id,
      }


  par = push_authorization_request(user_profile_id)
  ```
</CodeGroup>

`auth.claude.com`は、HTTP 201、`request_uri`、および600秒の`expires_in`を返します。`request_uri`は、このリクエストの承認ページを識別します。`scope`は正確に`billing:attribution`または`billing:attribution offline_access`である必要があります。詳細については、[請求接続のスコープ](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection)を参照してください。例では`billing:attribution`を送信しています。アプリにこのスコープがない場合は、アプリの**Permissions**タブの**Billing**で追加してください。

`connection_auth_target`は`platform`である必要があります。推論リクエストはあなた自身の組織内で実行され、オペレーターサービスアカウントとして認証しますが、顧客に請求できます。

`user_profile_id`は組織内のアクティブなユーザープロファイルのIDである必要があります。プッシュ型認可リクエストが失敗した場合、`auth.claude.com`はバックエンドにOAuthエラーレスポンスを返します。その場合、ブラウザをリダイレクトしないでください。

### ステップ6：ユーザーをClaudeの承認ページに送る

まず、製品内のどのアカウントをリンクしようとしているかをユーザーに示し、承認ページに表示されるClaudeアカウントを確認するようユーザーに伝えてください。ページには、どのClaudeアカウントでサインインしているかが表示され、ユーザーは別のアカウントに切り替えることができます。承認ページは、ブラウザでサインインしているClaudeアカウントの組織のみを提示するため、誤ったアカウントで誤った組織がリンクされる可能性があります。支払うのは、ユーザーがリンクした組織です。

<Note>
  承認する人は、顧客のClaude組織の管理者、つまり管理者または請求のロールを持つメンバーである必要があります。
</Note>

次に、ユーザーを、承認ページを表示する認可エンドポイントにリダイレクトします。`client_id`とステップ5の`request_uri`のみを含めてください。

```python
def authorize_url(par: dict) -> str:
    query = urlencode({"client_id": CLIENT_ID, "request_uri": par["request_uri"]})
    return f"{AUTH}/oauth/authorize?{query}"


redirect_to = authorize_url(par)  # answer the click with a 302 to this URL
```

### ステップ7：ユーザーが承認する

このステップでは、アプリは何も行いません。ユーザーは`auth.claude.com`で以下の手順を進めます：

1. ブラウザがすでにサインインしている場合を除き、ユーザーはClaudeにサインインします。

2. 承認ページには、それぞれアプリの名前を含む以下の画面が表示されます。各画面でユーザーが行うことについては、[リンク](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#connecting)を参照してください。

   1. **Select an organization**。ユーザーが組織を選択できる場合のみ表示されます。
   2. **How billing works**。
   3. **Set a monthly spend limit**。
   4. **Link and authorize**ボタンのある最後の画面。

3. ユーザーが**Link and authorize**をクリックすると、`auth.claude.com`はブラウザをアプリに戻します。承認ページには確認画面は表示されません。

ユーザーがキャンセルした場合や承認できない場合、接続は行われません。[リンクが完了しない場合](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#if-linking-doesnt-complete)を参照してください。

<Note>
  接続は、承認したユーザーではなく、Claude組織全体に属します。そのユーザーが組織を離れても、接続はアクティブなままです。顧客の組織またはあなたの組織の管理者であれば誰でも、いつでも接続を終了できます。バックエンドからも終了できます。
</Note>

### ステップ8：コールバックを処理して接続を保存する

承認後、`auth.claude.com`は1回限りのコードと`state`値を付けて、ブラウザをリダイレクトURIに戻します。このリダイレクトURIへのリクエストはコールバックと呼ばれます。バックエンドはコードを接続IDと交換し、それを顧客レコードに保存します。これで接続が完了します。コールバックには、コードの代わりに`error`パラメータが含まれる場合があります。その場合、接続は行われていません。[リンクが完了しない場合](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#if-linking-doesnt-complete)を参照してください。

`state`がステップ5で保存した値と一致することを確認してから、PKCEコードベリファイアとともに、バックエンドから直ちにコードを交換します。コードは1回のみ使用可能で、5分後に期限切れになります。

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/token \
    -H "content-type: application/json" \
    -d '{
      "grant_type": "authorization_code",
      "code": "AUTH_CODE",
      "code_verifier": "ORIGINAL_CODE_VERIFIER",
      "redirect_uri": "https://app.example.com/claude/billing/callback",
      "client_id": "YOUR_CLIENT_ID",
      "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
    }'
  ```

  ```python Python
  def handle_callback(par: dict, params: dict) -> str:
      if not secrets.compare_digest(
          params.get("state", "").encode(), par["state"].encode()
      ):
          raise ValueError("state does not match")
      if "error" in params:  # for example access_denied
          raise PermissionError(params["error"])
      code = params["code"]  # single-use, expires after 5 minutes
      response = httpx.post(
          f"{AUTH}/v1/oauth/token",
          json={
              "grant_type": "authorization_code",
              "code": code,
              "code_verifier": par["code_verifier"],
              "redirect_uri": REDIRECT_URI,
              "client_id": CLIENT_ID,
              "client_assertion_type": JWT_BEARER,
              "client_assertion": client_assertion(),
          },
          timeout=10,  # a response that times out loses the tokens in it
      )
      response.raise_for_status()
      tokens = response.json()
      # 接続のトークンを使用するには、tokens["access_token"]、その有効期限
      # （tokens["expires_in"] から算出）、および offline_access がある場合は
      # tokens["refresh_token"] をここでシークレットとして保存します。コードは再交換できません。
      # "ocon_..."。顧客レコードに保存します
      return tokens["connection_id"]
  ```
</CodeGroup>

レスポンスには接続IDと[接続のアクセストークン](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection)が含まれます。このアクセストークンで認証し、承認した顧客に請求できます。顧客が`offline_access`を承認した場合、レスポンスにはリフレッシュトークンも含まれます。`connection_id`とトークンはこの時点で保存してください。交換でトークンが返されるのは1回だけです。レスポンスについては[トークンを保存する](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#keep-the-tokens-from-step-8)で説明しています。

このページでClaude APIを呼び出す例は、このレスポンスのトークンではなく、ステップ3のサービスアカウントとして認証します。代わりにトークンを使用する方法については、[接続のアクセストークンでClaudeを呼び出す](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token)を参照してください。

レスポンスは、ユーザーがどのClaude組織をリンクしたかを示しません。

接続が完了しても、Anthropicが顧客に請求できることが保証されるわけではありません。たとえば、顧客の組織が[対象となる顧客](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints)に該当しない可能性があります。Claude APIがこれをどのように確認するかについては、[Claudeへの呼び出しを更新する](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#step-3-update-calls-to-claude)と[想定されるエラー](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#expected-errors)を参照してください。この確認があるため、成功メッセージは「請求が有効」ではなく「リンク済み」という表現にしてください。

交換が`unauthorized_client`で拒否された場合は、[コード交換が`unauthorized_client`を返す](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#code-exchange-unauthorized-client)を参照してください。

<Note>
  ユーザーは、すでにリンク済みのユーザープロファイルに対して再度承認できます。結果はスコープによって異なります：

  * 同じユーザープロファイルかつ同じスコープに対して再度承認された場合：接続は維持され、トークンレスポンスは同じ`connection_id`と新しいアクセストークンを返します。例外は`billing:attribution offline_access`の接続です。この場合、コード交換は`invalid_grant`を返し、接続はそのまま維持されます。対処方法については[顧客を再度リンクする](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again)を参照してください。
  * 同じユーザープロファイルに対して異なるスコープで再度承認された場合（たとえば、`billing:attribution`の後に`billing:attribution offline_access`）：新しいコードを交換すると、新しい`connection_id`を持つ新しい接続が作成され、以前の接続に置き換わります。以前の`billing:attribution`接続のトークンは取り消されます。以前の`connection_id`の代わりに新しい`connection_id`を保存してください。交換が5xxレスポンスで失敗した場合は、ステップ5から8を再度実行してください。これが必要になる場合については、[請求接続のスコープ](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection)を参照してください。
  * 接続が取り消された後は、同じユーザープロファイルを再度リンクできます。
</Note>

### 顧客としてテストする

リンクが機能することを確認するには、自身の組織をリンクします。まず以下が必要です：

* 顧客として機能する、あなたが所有する2つ目のClaude組織。アプリを所有している組織にそのアプリをリンクすることはできません。承認ページにはその組織が表示されません。2つ目の組織は[対象となる顧客](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints)のいずれかである必要があります。
* リンクを承認する、その組織で管理者または請求のロールを持つ人。
* アプリが本番稼働するまでは、その人がアプリの**Test users**リストに含まれている必要があります。このリストは、アプリの**設定**タブの**Who can link**の下にあります。その人のClaudeアカウントのメールアドレスで追加し、**Save changes**をクリックします。適用される支出上限については、[アプリのテスト中](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#while-your-app-is-in-testing)を参照してください。リストから人を削除すると、その人が承認したリンクが終了します。

次に、ステップ4から8を実行し、ステップ7でその人に承認してもらいます。リンクが完了すると、Consoleの[User profiles](https://platform.claude.com/user-profiles)ページで、ユーザープロファイルが**Linked**と表示されます。

### リンクが完了しない場合

ユーザーが承認を完了しない場合、または`auth.claude.com`が承認を拒否した場合、接続は行われません。以下の項目では、Linked billingに固有の結果について説明します。その他のすべてのエラーについては、OAuthリファレンスの[エラー](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/oauth-reference#errors)を参照してください。

#### リダイレクトURIが`error=access_denied`を受け取る

リクエストには`state`値も含まれます。リダイレクトURIは、たとえば以下のような場合にこのエラーを受け取ります：

1. ユーザーがいずれかの承認画面で**Cancel**をクリックした。

2. 承認ページにユーザーに提示できる組織がなく、ユーザーがアプリに戻るボタンをクリックした。たとえば：

   * ユーザーがどのClaude Platform組織でも管理者または請求のロールを持っていない。
   * ユーザーの唯一の組織が、アプリを所有している組織である。[顧客としてテストする](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#test-as-a-customer)を参照してください。
   * ユーザープロファイルがすでに別のClaude組織にリンクされており、ユーザーがその組織で管理者または請求のロールを持っていない。
   * アプリが本番稼働するまでの間、ユーザーがその**Test users**リストに含まれていない。

このリストのいずれの場合でも、`error_description`は`the user declined the request`となるため、これらを区別する手段にはなりません。

もう1つの原因はアプリの設定にあります。アプリが本番稼働していて、**Who can link**に自身の組織のみが表示されている場合、組織外の誰もアプリをリンクできません。**Any Claude user**を選択して**Save changes**をクリックしてください。

リンクが完了しなかったことをユーザーに伝え、ユーザーが拒否したとは決めつけないでください。どのClaudeアカウントでサインインしたか、およびリンクしたい組織でのロールを確認するようユーザーに依頼してください。ユーザーがキャンセルまたは戻った後は`request_uri`を再度使用できないため、ユーザーに再試行してもらうには、ステップ5からやり直してください。

#### アプリが`user_profile_already_linked`を受け取る

顧客のClaude組織が、あなたの別のユーザープロファイルを通じて、すでにアプリにリンクされています。`auth.claude.com`はユーザーにあなたへの問い合わせを求めます。ユーザーがアプリに戻った場合、リダイレクトURIは`error=user_profile_already_linked`と`state`値を受け取ります。ステップ8でコードを交換する際に、トークンエンドポイントがこのエラーを返すこともあります。これは、たとえばその間に組織が別のユーザープロファイルを通じてリンクされた場合に起こります。

Anthropicは、顧客がどのClaude組織をリンクするかをあなたに伝えないため、これを事前に知ることはできません。ステップ5のプッシュ型認可リクエストは成功し、`auth.claude.com`はユーザーが承認する時点で初めて接続を拒否します。

このエラーは、接続を保持しているユーザープロファイルを示しません。最も可能性が高いのは、この顧客の別のリンク済みプロファイルです。Anthropicはプロファイルがどの組織にリンクされているかを表示しないため、対応する前に顧客に確認してください。そのプロファイルが接続を保持している場合は、以下のいずれかを行ってください：

* この顧客に請求するリクエストで、そのユーザープロファイルのIDを送信する。
* [顧客のリンクを解除する](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer)の説明に従ってその接続を終了し、拒否されたユーザープロファイルでステップ5から8を再度実行する。

この顧客のプロファイルがいずれもリンクされていない場合、ユーザーがあなたの別の顧客に属する組織を選択した可能性があります。ステップ5からやり直し、どの組織を選択するかをユーザーに確認してもらってください。

#### リダイレクトURIが何も受け取らない

アプリは以下の2つのケースを検出できません：

* ユーザーが承認ページを閉じた。
* `request_uri`の有効期限が切れている、またはすでに使用されている。この場合、承認ページはエラーを表示し、ブラウザをアプリに戻しません。

ユーザーがコールバックなしで製品に戻ってきた場合は、ステップ5からやり直してください。使用されなかった`request_uri`は、作成してから10分後に期限切れになります。

#### コード交換が`unauthorized_client`を返す

アプリがこのリクエスト用に設定されていません。ワークスペースの問題の場合、`error_description`に原因が示されます。オペレーターサービスアカウントがない場合は、`the client is not registered for this grant`とだけ表示されます。拒否によってコードが消費されることはないため、期限が切れるまで同じコードを再度交換できます。まず、Claude Consoleで以下を確認してください：

| 確認事項                        | 場所                                                                                                                                                | 対処                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| アプリにオペレーターサービスアカウントがある      | アプリの**Client authentication**タブの**Operator service account**                                                                                      | 1つ選択して**Save**をクリックします。設定方法はステップ3で説明しています。                      |
| アプリのワークスペースが存在し、アーカイブされていない | [アプリを設定する](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) | ワークスペースを選択します。アプリにワークスペースがない間も、交換は`unauthorized_client`で拒否されます。 |

保存したサービスアカウントが`auth.claude.com`に反映されるまで1〜2分かかることがあるため、交換が再び拒否された場合は、それくらい待ってから再試行してください。それまでにコードの有効期限が切れた場合は、ユーザーに再度承認してもらってください（ステップ5から8）。接続のトークンについて`error_description`が示す原因については、[トークンを保存する](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#keep-the-tokens-from-step-8)と[トークンをリフレッシュする](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection)を参照してください。

それ以外の場合は、Anthropicのアカウントチームにお問い合わせください。サービスアカウントがもう存在しないとConsoleに表示される場合も同様です。

### アプリを公開する

アプリが公開されるまでは、アプリの**Test users**リストに含まれるユーザーのみがアプリをリンクできるため、顧客はリンクできません。アプリを公開するには、Claude Consoleのアプリのページで**Publish app**をクリックします。ダイアログボックスが開きます。

* 組織が請求書払いの場合は、そのダイアログボックスで確認するとすぐにアプリが公開されます。
* それ以外の場合は、まずそのダイアログボックスでアプリのドメインを管理していることを証明し、その後Anthropicがアプリを審査します。

**ドメインの証明：** ドメインとは、アプリのホームページのドメインです。すべてのリダイレクトURIは、`localhost`、`127.0.0.1`、または`[::1]`上のものを除き、そのドメインまたはそのサブドメイン上にある必要があります。証明にはDNS TXTレコードを使用します。DNSの変更には最大48時間かかることがあるため、顧客にリンクしてもらう必要が生じる前に開始してください。組織がホームページとそれらのリダイレクトURIをカバーするドメインをすでに証明している場合、ダイアログボックスでは証明がスキップされます。証明済みのドメインは、そのサブドメインもカバーします。

確認はダイアログボックスの最後のステップで行います。そのステップにLinked Billing Termsに同意するためのチェックボックスが表示された場合は、それを選択してください。次に、ダイアログボックスで**Publish app**をクリックします。

**審査：** 審査中、Consoleでのアプリのステータスは**In review**と表示されます。Anthropicが承認するとアプリが公開されます。Anthropicが承認しない場合、ステータスは**Not approved**と表示され、自分でアプリを再度公開することはできません。この決定について問い合わせるには、サポートにお問い合わせください。

組織が請求書払いでない限り、公開済みのアプリの名前、ロゴ、ホームページ、またはリダイレクトURIを変更すると、アプリは審査に戻ります。すでにリンクしている顧客はリンクされたままで、保存した上限も維持されます。Anthropicが変更を承認するまでは、**Test users**リストに含まれるユーザーのみがアプリをリンクできます。

## Claudeへの呼び出しを更新する

リンク済みの顧客に対する`/v1/messages`および`/v1/chat/completions`への各呼び出しで、`anthropic-user-profile-id`ヘッダーを送信します。顧客に請求するリクエストでは、ヘッダーの値は、その顧客の接続を保持しているユーザープロファイルのIDです。`billing_policy`を設定する呼び出しでは、`user-profiles-billing-2026-10-01`ベータヘッダーも送信する必要があります。

リンク済みの顧客に対する各リクエストは、顧客またはあなたのいずれかに請求され、どちらにするかはリクエストごとに選択します。以下の例で両方を示します。

[接続ごとのOAuthトークン](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection)では、顧客のリクエストを認証する別の方法、つまりその顧客にのみ請求できるアクセストークンについて説明しています。`/v1/messages`および`/v1/chat/completions`では、このようなトークンを使用したリクエストをあなたに請求することはできません。`billing_policy`や`anthropic-user-profile-id`ヘッダーがなくても、それらが任意である場合は、そのリクエストはその顧客に請求されます。[接続のアクセストークンでClaudeを呼び出す](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token)の注記を参照してください。リクエストが別のユーザープロファイルを指定しているか、`bill_to: "self"`を設定している場合は拒否されます。あなたが支払うリクエストには、このトークンを決して使用しないでください。

### 顧客が支払う場合

リクエストボディに`bill_to: "user_profile"`を指定した`billing_policy`を追加し、請求ベータヘッダーとプロファイルIDヘッダーを送信します。

<Warning>
  ヘッダーが、リクエストの対象となる顧客のプロファイルを指定していることを確認してください。デフォルトでは、オペレーターサービスアカウント自身の認証情報で、このアプリを通じてリンクされたすべての顧客に請求できます。その認証情報を使用したリクエストが、このアプリを通じてリンクされた別のプロファイルを指定した場合、Anthropicはそのプロファイルの組織に請求し、エラーで知らされることはありません。[接続のアクセストークン](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection)は、その接続自身の顧客にのみ請求できます。
</Warning>

`bill_to: "user_profile"`は、顧客の指示によって行うリクエスト、つまり顧客とそのユーザーがあなたの製品内で発生させるClaudeの使用量に対してのみ設定してください。テスト、評価、または他の顧客のための作業など、あなた自身の使用量を顧客に請求しないでください。Claude APIはこれを確認できないため、これはあなたの責任となります。

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: user-profiles-billing-2026-10-01" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}],
      "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
    }'
  ```

  ```bash CLI
  ant beta:messages create \
    --beta user-profiles-billing-2026-10-01 \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}' <<'YAML'
  billing_policy:
    type: billing_policy
    bill_to: user_profile
  YAML
  ```

  ```python Python
  def message_billed_to_user(user_profile_id: str, prompt: str) -> BetaMessage:
      return client.beta.messages.create(
          model="claude-opus-5-5",
          max_tokens=1024,
          messages=[{"role": "user", "content": prompt}],
          betas=[BILLING_BETA],
          extra_headers={"anthropic-user-profile-id": user_profile_id},
          extra_body={
              "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
          },
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.beta.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    // @ts-expect-error: billing_policy isn't in the SDK's types yet
    billing_policy: { type: "billing_policy", bill_to: "user_profile" }
  });

  console.log(message.content);
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Messages;
  using System.Text.Json;
  using Model = Anthropic.Models.Messages.Model;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 1024,
      Messages = [new BetaUserMessageParam { Content = "Hello, Claude" }],
      Betas = ["user-profiles-billing-2026-10-01"],
      UserProfileID = "uprof_01HV9Z",
  };
  // billing_policy はまだ SDK の型に含まれていません
  var body = new Dictionary<string, JsonElement>(parameters.RawBodyData)
  {
      ["billing_policy"] = JsonSerializer.SerializeToElement(
          new { type = "billing_policy", bill_to = "user_profile" }
      ),
  };

  var message = await client.Beta.Messages.Create(
      MessageCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body)
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  params := anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),
  	},
  	Betas:         []anthropic.AnthropicBeta{"user-profiles-billing-2026-10-01"},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  }
  params.SetExtraFields(map[string]any{
  	"billing_policy": map[string]string{
  		"type":    "billing_policy",
  		"bill_to": "user_profile",
  	},
  })

  message, err := client.Beta.Messages.New(context.Background(), params)
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.core.JsonValue;
  import com.anthropic.models.beta.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;
  import java.util.Map;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .addBeta("user-profiles-billing-2026-10-01")
          .userProfileId("uprof_01HV9Z")
          .putAdditionalBodyProperty("billing_policy", JsonValue.from(Map.of(
              "type", "billing_policy",
              "bill_to", "user_profile")))
          .build();
      var message = client.beta().messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->beta->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      betas: ['user-profiles-billing-2026-10-01'],
      userProfileID: 'uprof_01HV9Z',
      requestOptions: [
          'extraBodyParams' => [
              'billing_policy' => ['type' => 'billing_policy', 'bill_to' => 'user_profile'],
          ],
      ],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.beta.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    request_options: {
      extra_body: { billing_policy: { type: "billing_policy", bill_to: "user_profile" } }
    }
  )

  puts(message.content)
  ```
</CodeGroup>

リクエストが拒否された場合は、[想定されるエラー](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#expected-errors)を参照してください。

### あなたが支払う場合

あなた自身が支払うには、`billing_policy`を完全に省略する（この場合、請求ベータヘッダーは任意です）か：

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}'
  ```

  ```python Python
  def message_billed_to_you(user_profile_id: str, prompt: str) -> Message:
      return client.messages.create(
          model="claude-opus-5-5",
          max_tokens=1024,
          messages=[{"role": "user", "content": prompt}],
          user_profile_id=user_profile_id,
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    user_profile_id: "uprof_01HV9Z"
  });

  console.log(message.content);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var message = await client.Messages.Create(
      new MessageCreateParams
      {
          Model = Model.ClaudeSonnet5_5,
          MaxTokens = 1024,
          Messages = [new UserMessageParam { Content = "Hello, Claude" }],
          UserProfileID = "uprof_01HV9Z",
      }
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),
  	},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.models.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .userProfileId("uprof_01HV9Z")
          .build();
      var message = client.messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      userProfileID: 'uprof_01HV9Z',
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    user_profile_id: "uprof_01HV9Z"
  )

  puts(message.content)
  ```
</CodeGroup>

または`bill_to: "self"`を使用します：

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: user-profiles-billing-2026-10-01" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}],
      "billing_policy": {"type": "billing_policy", "bill_to": "self"}
    }'
  ```

  ```bash CLI
  ant beta:messages create \
    --beta user-profiles-billing-2026-10-01 \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}' <<'YAML'
  billing_policy:
    type: billing_policy
    bill_to: self
  YAML
  ```

  ```python Python
  def message_billed_to_self(user_profile_id: str, prompt: str) -> BetaMessage:
      return client.beta.messages.create(
          model="claude-opus-5-5",
          max_tokens=1024,
          messages=[{"role": "user", "content": prompt}],
          betas=[BILLING_BETA],
          extra_headers={"anthropic-user-profile-id": user_profile_id},
          extra_body={"billing_policy": {"type": "billing_policy", "bill_to": "self"}},
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.beta.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    // @ts-expect-error: billing_policy isn't in the SDK's types yet
    billing_policy: { type: "billing_policy", bill_to: "self" }
  });

  console.log(message.content);
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Messages;
  using System.Text.Json;
  using Model = Anthropic.Models.Messages.Model;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 1024,
      Messages = [new BetaUserMessageParam { Content = "Hello, Claude" }],
      Betas = ["user-profiles-billing-2026-10-01"],
      UserProfileID = "uprof_01HV9Z",
  };
  // billing_policy はまだ SDK の型に含まれていません
  var body = new Dictionary<string, JsonElement>(parameters.RawBodyData)
  {
      ["billing_policy"] = JsonSerializer.SerializeToElement(
          new { type = "billing_policy", bill_to = "self" }
      ),
  };

  var message = await client.Beta.Messages.Create(
      MessageCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body)
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  params := anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),
  	},
  	Betas:         []anthropic.AnthropicBeta{"user-profiles-billing-2026-10-01"},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  }
  params.SetExtraFields(map[string]any{
  	"billing_policy": map[string]string{
  		"type":    "billing_policy",
  		"bill_to": "self",
  	},
  })

  message, err := client.Beta.Messages.New(context.Background(), params)
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.core.JsonValue;
  import com.anthropic.models.beta.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;
  import java.util.Map;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .addBeta("user-profiles-billing-2026-10-01")
          .userProfileId("uprof_01HV9Z")
          .putAdditionalBodyProperty("billing_policy", JsonValue.from(Map.of(
              "type", "billing_policy",
              "bill_to", "self")))
          .build();
      var message = client.beta().messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->beta->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      betas: ['user-profiles-billing-2026-10-01'],
      userProfileID: 'uprof_01HV9Z',
      requestOptions: [
          'extraBodyParams' => [
              'billing_policy' => ['type' => 'billing_policy', 'bill_to' => 'self'],
          ],
      ],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.beta.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    request_options: {
      extra_body: { billing_policy: { type: "billing_policy", bill_to: "self" } }
    }
  )

  puts(message.content)
  ```
</CodeGroup>

## 接続ごとのOAuthトークン

バックエンドは、アプリのオペレーターサービスアカウント（ステップ3）としてClaude APIを呼び出します。デフォルトでは、そのサービスアカウントとして認証された任意のリクエストが、ユーザープロファイルIDヘッダーを渡し、Messages APIリクエストに`bill_to`を含めることで、リンク済みのすべての顧客に請求できます。このデフォルトを「operator-only tokenless authentication」（オペレーターのみのトークンレス認証）と呼びます。

製品のシングルテナントデプロイメントや、顧客が管理するサンドボックス環境に対応するために、オペレーターのみのトークンレス認証を使用する代わりに、接続にバインドされたOAuthアクセストークンとリフレッシュトークンを取得できます。

各接続について、ステップ8のコード交換はその接続独自のアクセストークンを返します。このトークンはオペレーターサービスアカウントとして認証しますが、請求できるのはその接続の顧客のみです。有効期限は1時間以内です。

各接続を個別に認証するには：

* **オフラインアクセスを使用する。** アプリの[**Offline access**](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens)を有効にし、ステップ5で`offline_access`をリクエストします。これにより、各接続はリフレッシュトークンも取得し、バックエンドはそれを使用して新しいアクセストークンをリクエストします。これがない場合、新しいアクセストークンを得るには顧客が再度承認する必要があります。同じ`scope`でステップ5から8を再度実行してください。
* **デフォルトのワークスペースを設定する。** これらのトークンを使用したリクエストを実行するワークスペースを、組織内で[選択します](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens)。
* **必要に応じて、オペレーターのみのトークンレス認証を無効にする。** デフォルトでは、顧客のアクセストークンの有効期限が切れた後でも、オペレーターサービスアカウントとして（ユーザープロファイルヘッダーと`bill_to`を渡すことで）リンク済みの顧客に請求できます。[オペレーターのみの認証をオフにした](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication)後は、顧客に請求するすべてのリクエストがその顧客のアクセストークンで認証する必要があります。
* **`billing:attribution`を使用する。** 接続に独自のトークンを与えるのはこのスコープのみです。非推奨の`org:billing_attribution`と同様に、引き続きオペレーターサービスアカウントとしてリンク済みの顧客に請求できます。[請求接続のスコープ](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection)を参照してください。

### アプリを設定する

接続のアクセストークンを使用したリクエストは、組織内の1つのワークスペースで実行されます。これらのトークンを使用しない場合でも、すべてのアプリにワークスペースが必要です。アプリにワークスペースがない間は、ステップ8のコード交換は`unauthorized_client`で拒否されます。

管理者のロールを持つ組織のメンバーが、Consoleでアプリの**Client authentication**タブを開きます。オペレーターサービスアカウントの下にある**Default workspace for platform auth mode OAuth tokens**（アプリの`connection_token_workspace_id`設定）を見つけ、**Choose workspace**をクリックします。オペレーターサービスアカウント（ステップ3）がメンバーであるワークスペースを選択します。ワークスペースはアーカイブされていてはいけません。

リフレッシュトークンを取得するには、アプリの**Permissions**タブで**Offline access**を有効にします。アプリのスコープへの変更が`auth.claude.com`に反映されるまでには数分かかります。

<Note>
  デフォルトのワークスペースをアーカイブすると、そこで実行されるすべてのトークンが取り消され、元に戻すことはできません。別のワークスペースに移行するには、新しいワークスペースを設定して数分待ちます。変更が`auth.claude.com`に反映される前にリフレッシュすると、引き続き以前のワークスペースで実行されるトークンが返されることがあります。その後、リフレッシュトークンを持つすべての接続をリフレッシュし、それが済んでから以前のワークスペースをアーカイブしてください。先にワークスペースをアーカイブした場合は、別のワークスペースを設定する前に、その接続のリフレッシュを停止してください。その後にリフレッシュすると、接続が終了します。

  顧客がリンクしている間は、アプリのオペレーターサービスアカウントを変更またはアーカイブしないでください。変更またはアーカイブすると、`auth.claude.com`はすべてのリフレッシュを拒否し、あなたが保持しているトークンはまもなく顧客に請求できなくなります。その場合、あなたがトークンを使用している各顧客は、再度リンクする必要があります。サポートが必要な場合は、[サポートにお問い合わせください](https://support.claude.com/en/articles/9015913-how-to-get-support)。
</Note>

### 請求接続のスコープ

ステップ5では、`scope`として`billing:attribution`を送信します。リフレッシュトークンも取得するには、`billing:attribution offline_access`を送信します。

すでにリンク済みの顧客のスコープを変更するには（たとえば`offline_access`を追加する場合）、顧客の既存のユーザープロファイルと新しい`scope`を使用してステップ5から8を再度実行します。先にリンクを解除する必要はありません。コードの交換によって新しい`connection_id`が返され、新しい接続が以前の接続を置き換えます。ステップ8の注記を参照してください。

アプリは、`billing:attribution`と非推奨の`org:billing_attribution`を同時に持つことができます。`billing:attribution`は、アプリの**Permissions**タブの**Billing**の下で追加します。そこで`org:billing_attribution`を削除すると、再度追加することはできません。顧客が`org:billing_attribution`で承認した接続は、接続が終了するか、あなたが[オペレーターのみの認証をオフにする](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication)まで、オペレーターサービスアカウントを通じて請求を続けます。

### トークンを保存する

コードの交換でトークンが返されるのは1回のみであるため、ステップ8でトークンを保存してください。レスポンスには、`access_token`、`expires_in`（最大1時間、秒単位）、および`connection_id`が含まれます。顧客が`offline_access`を承認した場合は、`refresh_token`と`refresh_token_expires_in`も含まれます。リフレッシュトークンの有効期間は最大1年で、リフレッシュしてもその期間は延長されません。期限が過ぎたら、[顧客を再度リンク](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again)してください。

トークンとその有効期限は、リフレッシュを行うサービスのみが読み取れるシークレットストアに保存してください。

交換が`unauthorized_client`で拒否された場合、`error_description`には、ワークスペースが存在しない、またはアーカイブされているなどの原因が示されます。コードは消費されていません。原因を修正し、期限が切れる前に同じコードを再度送信してください。

### 接続のアクセストークンでClaudeを呼び出す

<Note>
  ベータ期間中は、接続のアクセストークンを使用したClaude APIリクエストがあなたの組織で有効になっているかどうかを、Anthropicのアカウントチームに確認してください。有効になっていない間は、そのようなリクエストは何を送信してもすべて失敗します。また、`anthropic-user-profile-id`ヘッダーと`billing_policy`が任意かどうかも確認してください。任意でない間は、接続のアクセストークンを使用するすべての`/v1/messages`および`/v1/chat/completions`リクエストを、[顧客が支払う場合](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#your-customer-pays)に示すとおり、ヘッダー、`bill_to: "user_profile"`、および請求ベータヘッダーを付けて送信してください。
</Note>

接続のアクセストークンを、オペレーターサービスアカウント自身の認証情報の代わりに、`Authorization`ヘッダーのベアラートークンとして送信します。`x-api-key`ヘッダーは送信しないでください。Anthropic SDKでは、トークンを`auth_token` (typescript, php: `authToken`; java: `.authToken()`; csharp: `AuthToken`; go: `option.WithAuthToken()`)として渡すか、`ANTHROPIC_AUTH_TOKEN`環境変数を設定します。

`/v1/messages`と`/v1/chat/completions`では、リクエストはその接続の顧客に請求されます。`anthropic-user-profile-id`ヘッダーと`billing_policy`は任意です。請求ベータヘッダーが必要なのは、`billing_policy`を使用する場合のみです。

これら2つのエンドポイントでは、このトークンを使用してあなたが支払うリクエストを送信することはできません。このトークンは、これら2つのエンドポイント、`/v1/messages/count_tokens`、およびModelsエンドポイントでのみ使用してください。その他のすべてのリクエストと、あなたが支払うすべてのリクエストは、自身のバックエンドから、オペレーターサービスアカウントとして送信してください。これには、顧客に請求できない[課金対象のコード実行機能](https://platform.claude.com/docs/ja/about-claude/pricing#code-execution-tool)を使用するリクエストも含まれます。

Claude APIは以下のリクエストを拒否します：

* `400 invalid_request_error`（エラーコードなし）：リクエストが別のユーザープロファイルを指定したか、`bill_to: "self"`を設定しました。
* `403 permission_error`（エラーコードなし）：リクエストが[Message Batches](https://platform.claude.com/docs/ja/build-with-claude/batch-processing)エンドポイントに送信されました。
* `401 authentication_error`：トークンの有効期限が切れた、リフレッシュによって置き換えられた、またはその接続が終了しました。接続が終了した後は、レスポンスが`403 user_profile_not_billable`になることもあります。

### トークンをリフレッシュする

接続のアクセストークンを更新するには、そのリフレッシュトークンを、アプリの[クライアント認証](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/oauth-reference#client-authentication)とともにトークンエンドポイント`https://auth.claude.com/v1/oauth/token`に送信します。`scope`パラメータは送信しないでください。

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/token \
    -H "content-type: application/json" \
    -d @- <<JSON
  {
    "grant_type": "refresh_token",
    "refresh_token": "$CONNECTION_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": "$CLIENT_ASSERTION"
  }
  JSON
  ```

  ```python Python
  connection_locks: defaultdict[str, threading.Lock] = defaultdict(threading.Lock)


  def error_body(response: httpx.Response) -> dict:
      try:
          body = response.json()
      except ValueError:
          return {}
      return body if isinstance(body, dict) else {}


  def is_lost(response: httpx.Response) -> bool:
      """True for a 5xx response that can follow a refresh that took effect."""
      if response.status_code < 500:
          return False
      # retry-afterヘッダー付きのClaude API形式の503は、拒否応答であり
      # リフレッシュトークンを使用しません。その他の5xx応答はすべて失われたものとみなします。
      paused = (
          response.status_code == 503
          and error_body(response).get("type") == "error"
          and "retry-after" in response.headers
      )
      return not paused


  def hold_error(connection_id: str, reason: str) -> RefreshOnHold:
      return RefreshOnHold(
          f"Connection {connection_id} is on hold. {reason} Don't send its refresh token"
          ' again: that can end the connection. See "Link a customer again" in the'
          " Linked billing guide."
      )


  def refresh_connection(connection_id: str, *, force: bool = False) -> tuple[str, int]:
      """Refreshes the connection if its access token is close to its expiry.

      Returns the current access token and its expiry time in Unix seconds. Call
      this from your schedule, and pass force=True to refresh a token that isn't
      close to its expiry. Raises RefreshOnHold when the refresh token can't be sent
      again, now and on every later call, and httpx.HTTPStatusError for a refusal
      that keeps the refresh token. After RefreshOnHold for a lost refresh, pause
      your schedule. Resume with one connection, and resume the others only after
      that refresh succeeds or gets a 4xx.
      """
      # このロックは1プロセス内でのみ機能します。サービスにレプリカがある場合は、
      # すべてのレプリカで共有するロックを使用してください。
      with connection_locks[connection_id]:
          tokens = load_tokens(connection_id)
          if tokens.on_hold:
              raise hold_error(
                  connection_id, "An earlier refresh might have used its refresh token."
              )
          if not force and tokens.expires_at - time.time() > REFRESH_MARGIN_SECONDS:
              return tokens.access_token, tokens.expires_at  # not close to expiry
          request = {
              "grant_type": "refresh_token",
              "refresh_token": tokens.refresh_token,
              "client_id": CLIENT_ID,
              "client_assertion_type": JWT_BEARER,
              "client_assertion": client_assertion(),
          }
          url = f"{AUTH}/v1/oauth/token"
          # リフレッシュトークンがこのプロセスを離れる前に、接続を保留状態にします。
          # 新しいトークンの保存前にプロセスが停止した場合、保留状態は残ります。
          save_tokens(connection_id, replace(tokens, on_hold=True))
          issued_at = int(time.time())
          started = time.monotonic()
          # httpxは自動でリトライしません。リトライを追加しないでください。遅れたリトライは
          # 接続を終了させます。
          try:
              response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
              lost = is_lost(response)
          except (httpx.ConnectError, httpx.ConnectTimeout):
              # 接続は確立されなかったため、リフレッシュトークンはこのプロセスから出ていません。
              save_tokens(connection_id, tokens)
              raise
          except httpx.TransportError:
              lost = True
          if lost:
              # 1回目のリクエストがリフレッシュトークンを使用した可能性があります。2回目のリクエストは
              # 上記の制限内でのみ安全なため、すぐに1回送るか、まったく
              # 送らないかのどちらかにします。
              if time.monotonic() - started > SECOND_REQUEST_DEADLINE_SECONDS:
                  raise hold_error(connection_id, "A refresh got no usable answer.")
              try:
                  response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
              except httpx.TransportError:
                  raise hold_error(
                      connection_id, "Two refreshes got no answer."
                  ) from None
              if response.status_code != 200:
                  # 新しいトークン以外の応答の後は、
                  # 1回目のリクエストが反映されたか判断できず、後からのリクエストは安全ではありません。
                  raise hold_error(connection_id, "The second refresh failed.")
          if error_body(response).get("error") == "invalid_grant":
              # 期限切れ、使用済み、または接続が終了しています。再送すると
              # 接続が終了する可能性があります。
              raise hold_error(connection_id, "The refresh returned invalid_grant.")
          if response.status_code != 200:
              # リフレッシュトークンを保持したままの拒否応答なので、保留を解除します。
              save_tokens(connection_id, tokens)
              response.raise_for_status()
          body = response.json()
          tokens = ConnectionTokens(
              refresh_token=body["refresh_token"],
              access_token=body["access_token"],
              expires_at=issued_at + body["expires_in"],
              refresh_expires_at=issued_at + body["refresh_token_expires_in"],
          )
          # 書き込みに失敗した場合は書き込みを再試行します。リフレッシュは再実行しないでください。
          for attempt in range(5):
              try:
                  save_tokens(connection_id, tokens)
                  return tokens.access_token, tokens.expires_at
              except OSError:  # your secret store's error type
                  if attempt < 4:
                      time.sleep(2**attempt)
          # 新しいトークンはこのプロセス内にしか存在せず、保存済みのリフレッシュトークンは
          # 使用済みです。保存済みレコードはまだ保留状態です。エラーは新しいトークンを保持するため、
          # シークレットストアが復旧したときに呼び出し元が保存できます。
          error = hold_error(
              connection_id,
              "The refresh succeeded, but the new tokens could not be saved.",
          )
          error.new_tokens = tokens
          raise error
  ```
</CodeGroup>

レスポンスには、新しい`access_token`と新しい`refresh_token`が含まれます。送信したリフレッシュトークンは置き換えられます。以下の失敗のリストで示す場合を除き、再度送信しないでください。以前のアクセストークンは数分以内に使用できなくなります。例で呼び出している関数は、[OAuthトークンのコードスニペットの初期化](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#oauth-token-snippet-initialization)で定義されています。

* 新しいアクセストークンを使用する前に、新しいリフレッシュトークンを保存してください。
* 各接続のトークンのリフレッシュは、1つのサービスから、一度に1回ずつ行ってください。サービスにレプリカがある場合は、すべてのレプリカが共有するロックを使用してください。使用済みのリフレッシュトークンが最初の使用から30秒以上経ってから再度届くと、接続が終了します。すべてのトークンが取り消され、顧客は**Unlinked**と表示され、顧客が再度リンクするまで、どの認証情報でも顧客に請求できなくなります。
* HTTPクライアントおよびプロキシで、リフレッシュリクエストの自動再試行をオフにしてください。

リフレッシュトークンを使用した最初のリクエストが失敗した場合：

* リクエストが接続できなかった：リフレッシュトークンは送信されていません。後で再試行してください。

* 接続が切断された、またはこのリストの`503`以外の5xxレスポンスが返された：リクエストが反映されたかどうかを判断できないため、同じリフレッシュトークンをもう一度だけ送信してください。

  1. 直ちに送信してください。ただし、最初のリクエストを送信してから30秒未満の場合に限ります。
  2. 新しいトークンが返された場合は、それを保存し、それのみを使用してください。最初のリクエストが反映されていた場合、あなたに届かなかったそのトークンは取り消されます。
  3. それ以外が返された、応答がなかった、または30秒が経過した場合は、そのリフレッシュトークンを再度送信しないでください。その接続のリフレッシュを停止し、[顧客を再度リンク](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again)してください。

* タイムアウトした：リクエストがまだ実行中である可能性があります。そのリフレッシュトークンを再度送信しないでください。その接続のリフレッシュを停止し、[顧客を再度リンク](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again)してください。

* `429`、または`retry-after`ヘッダーがあり、ボディの最上位に`"type": "error"`がある`503`：何も取り消されていません。少なくともヘッダーが示す時間だけ待ってから、同じリフレッシュトークンを再度送信してください。

* `unauthorized_client`または`invalid_client`：何も取り消されていません。`error_description`には、ワークスペースが存在しない、アプリに`offline_access`が登録されなくなった、クライアントアサーションが失敗したなどの原因が示されます。それを修正し、同じリフレッシュトークンを再度送信してください。

* `invalid_scope`：リクエストが`scope`パラメータを送信したか、アプリに`billing:attribution`が登録されなくなりました。何も取り消されていません。原因を修正し、同じリフレッシュトークンを再度送信してください。

* `invalid_grant`：リフレッシュトークンの有効期限が切れた、またはすでに使用された、接続が終了した、あるいは顧客の組織が停止されています。その接続のリフレッシュを停止し、[顧客を再度リンクする](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again)に従ってください。これは停止の確認から始まります。

接続の切断、5xxレスポンス、またはタイムアウトによって接続のリフレッシュを停止した場合は、他の接続のリフレッシュも一時停止してください。再開する際は、まず1つの接続をリフレッシュし、そのリフレッシュが成功するか4xxレスポンスを受け取った後にのみ、他の接続を再開してください。

### サンドボックスでエージェントを実行する

サンドボックスにはアクセストークンのみを渡し、リフレッシュトークンは決して渡さないでください。リフレッシュはバックエンドが行い、新しいアクセストークンをその都度サンドボックスに送信します。バックエンドは、サンドボックスがどの顧客にサービスを提供するかを、ポッドのアイデンティティなどのサンドボックス自身のアイデンティティから判断し、サンドボックスが送信する値からは決して判断しません。サンドボックスにはその顧客のトークンのみを送信します。サンドボックスが、フェデレーションルールまたはアプリのクライアント認証のいずれかに一致するJWTを取得できてはなりません。マウントされたアイデンティティトークンを与えず、クラウドのメタデータサーバーへのアクセスも与えないでください。

Claude Code、[Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview)、およびAnthropic SDKは、設定プロファイル内の認証情報ファイルからトークンを読み取ることができます（[プロファイル設定ファイル](https://platform.claude.com/docs/ja/manage-claude/wif-reference#profile-configuration-file)を参照）。サンドボックス内に、このプロファイルを含む設定ディレクトリを作成します。`client_id`は追加しないでください。追加すると、SDKがトークンを自らリフレッシュしようとします。

```json configs/customer.json
{
  "version": "1.0",
  "authentication": {
    "type": "user_oauth"
  }
}
```

エージェントが起動する前と各リフレッシュの後に、アクセストークンを同じディレクトリ内の`credentials/customer.json`として書き込みます。`expires_at`はUnix秒での有効期限です。モード`0600`で新しいファイルを書き込み、それを古いファイルに上書きする形でリネームします：

```json credentials/customer.json
{
  "type": "oauth_token",
  "access_token": "sk-ant-oat01-...",
  "expires_at": 1793635200
}
```

`ANTHROPIC_CONFIG_DIR`を設定ディレクトリに、`ANTHROPIC_PROFILE`を`customer`に設定します。`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`CLAUDE_CODE_OAUTH_TOKEN`、Claude Codeの`apiKeyHelper`設定など、サンドボックス内のその他の認証情報はすべて設定を解除してください。いずれもプロファイルより優先される可能性があるためです。エージェントは、`expires_at`の前の最後の2分間と、401レスポンスの後にファイルを再度読み取ります。

```python
def write_credentials_file(
    config_dir: Path, profile: str, token: str, expires_at: int
) -> None:
    credentials_dir = config_dir / "credentials"
    credentials_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
    body = {"type": "oauth_token", "access_token": token, "expires_at": expires_at}
    # 完成したファイルをリネームして配置し、エージェントが不完全なファイルを読まないようにします。
    # mkstempは現在のユーザーを所有者としてモード0600を設定するため、これは
    # エージェントのユーザーとして実行してください。
    handle, temporary_path = tempfile.mkstemp(dir=credentials_dir)
    with os.fdopen(handle, "w") as temporary_file:
        json.dump(body, temporary_file)
    os.replace(temporary_path, credentials_dir / f"{profile}.json")
```

### 顧客を再度リンクする

以下の場合は、顧客を再度リンクしてください：

* リフレッシュが`invalid_grant`を返した。
* リフレッシュトークンを紛失した、または漏洩した。
* `billing:attribution offline_access`に対するステップ8のレスポンスを失った、またはそのような接続に対してステップ8が`invalid_grant`を返した。
* リフレッシュトークンの有効期限が近づいている。

以下の手順に従ってください：

1. [User profiles](https://platform.claude.com/user-profiles)ページで、顧客が**Linked**と表示されているかどうかを確認します。`invalid_grant`の後は、まず顧客の組織が停止されているかどうかをAnthropicのアカウントチームに確認してください。停止が解除されると、保持しているリフレッシュトークンは再び機能します。すべての接続が同時に`invalid_grant`を返す場合は、誰かのリンクを解除する前に、アーカイブされたワークスペースなど、あなたの側の原因を探してください。
2. 顧客が**Linked**と表示されている場合は、[顧客のリンクを解除する](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer)の説明に従ってリンクを解除します。リンクを解除すると、接続のトークンが取り消されます。承認するまで接続を通じた請求が停止するため、顧客の組織の管理者が承認する準備ができているときに行ってください。
3. 顧客の既存のユーザープロファイルを使用して、ステップ5から8を再度実行します。新しい接続IDと新しいトークンを、以前のものの代わりに保存します。

### オペレーターのみの認証をオフにする

<Note>
  ベータ期間中は、この設定があなたの組織で利用可能かどうかをAnthropicのアカウントチームに確認してください。利用可能でない間は、オンにすることはできません。
</Note>

オペレーターサービスアカウントとしてのみ認証するリクエストが顧客に請求されないようにするには、**Disable operator-only tokenless authentication**（アプリの`disable_operator_only_auth`設定）をオンにします。これは、アプリの**Client authentication**タブのオペレーターサービスアカウントの下にあります。アプリには、`billing:attribution`および`offline_access`スコープと、[OAuthトークン用のワークスペース](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens)が必要です。オンにする前に、リンク済みのすべての顧客が`billing:attribution offline_access`を承認していること、および顧客のアクセストークンを使用したリクエストが機能することを確認してください。オンの間は、`billing:attribution`接続のアクセストークンのみが、その接続の顧客に請求できます。サービスアカウントのみとして認証し、`bill_to: "user_profile"`を設定したリクエストは、`403 user_profile_not_billable`で拒否されます。顧客は引き続き**Linked**と表示されるため、ログでこのエラーを監視してください。サービスアカウントは引き続き、ユーザープロファイルを管理し、あなたが支払うリクエストを送信できます。この設定は再度オフにできます。

### OAuthトークンのコードスニペットの初期化

このセクションの例は、以下の共通のセットアップを使用します。以下を定義します：

* インポート（`httpx`パッケージを含む）
* アプリのクライアントIDとクライアントアサーションのタイプ
* `ConnectionTokens`。接続のトークン、その有効期限、および`on_hold`マークを保持します
* `RefreshOnHold`。リフレッシュトークンを再度送信してはならない場合に`refresh_connection()`が発生させるエラーです。そのリフレッシュトークンはすでに使用されている可能性があるか、トークンエンドポイントが`invalid_grant`を返しました。保存されたトークンの`on_hold`を解除するまで（たとえば停止が解除された後など）、`refresh_connection()`は以降のすべての呼び出しでもこのエラーを発生させます。リフレッシュが成功し、シークレットストアへの書き込みのみが拒否された場合、その`new_tokens`に保存すべきトークンが保持されます。
* `client_assertion()`。`ANTHROPIC_IDENTITY_TOKEN_FILE`が指定するファイルから、アイデンティティプロバイダーのJWTを読み取ります。JWTの`aud`クレームは、アプリのクライアント認証設定のオーディエンスである必要があります。
* `load_tokens()`と`save_tokens()`。自身のシークレットストア向けにあなたが記述します

```python
import json
import os
import tempfile
import threading
import time
from collections import defaultdict
from dataclasses import dataclass, field, replace
from pathlib import Path

import httpx

AUTH = "https://auth.claude.com"
# OAuthアプリを登録した後、platform.claude.comからコピーします。
CLIENT_ID = "YOUR_CLIENT_ID"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
REFRESH_MARGIN_SECONDS = 600
# ここでタイムアウトしたリフレッシュは新しいトークンを失うため、応答には10秒を確保します。
# 応答を待ちます。接続できない場合は2秒以内に失敗します。
REQUEST_TIMEOUT = httpx.Timeout(10, connect=2)
# 2回目のリクエストは1回目の直後のこの時間内に開始するか、まったく送らないでください。
# ページでは30秒としていますが、REQUEST_TIMEOUTの読み取りタイムアウト未満に保ちます。
# タイムアウトしたリクエストは再送してはいけません。
SECOND_REQUEST_DEADLINE_SECONDS = 4


@dataclass
class ConnectionTokens:
    refresh_token: str = field(repr=False)
    access_token: str = field(repr=False)
    expires_at: int  # the access token's expiry time, in Unix seconds
    refresh_expires_at: int  # the refresh token's expiry time, in Unix seconds
    # True: リフレッシュトークンが使用された可能性があります。再送しないでください。
    on_hold: bool = False


class RefreshOnHold(Exception):
    """The refresh token might have been used, so a person decides what to do next.

    Don't catch this to try again. If new_tokens is set, the refresh succeeded and
    only the write failed: store those tokens.
    """

    new_tokens: ConnectionTokens | None = None


def client_assertion() -> str:
    """Reads your identity provider's JWT on every call, because its file rotates."""
    return Path(os.environ["ANTHROPIC_IDENTITY_TOKEN_FILE"]).read_text().strip()


def load_tokens(connection_id: str) -> ConnectionTokens:
    """Reads the connection's newest tokens from your secret store."""
    raise NotImplementedError("Read the tokens from your secret store.")


def save_tokens(connection_id: str, tokens: ConnectionTokens) -> None:
    """Writes the connection's newest tokens to your secret store."""
    raise NotImplementedError("Write the tokens to your secret store.")
```

## 接続の管理

### Consoleで顧客を表示する

OAuthアプリページに加えて、Consoleの[User profiles](https://platform.claude.com/user-profiles)ページですべてのユーザープロファイルを表示できます。そのリストと各ユーザープロファイルの詳細ページで、**Your spend**は、そのユーザープロファイルのリクエストに対するあなた自身のコストです。これは、Anthropicがクレジットを適用する前のコストです。これらのページでは接続を「リンク」と呼びます。接続がアクティブなユーザープロファイルには**Linked**、接続が終了したユーザープロファイルには**Unlinked**と表示されます。

ユーザープロファイルをクリックすると、過去7日間、28日間、または90日間の使用量のより詳細なビューが表示されます。

### 各顧客の使用量を監視する

Claude Consoleと[Usage and Cost Analytics API](https://platform.claude.com/docs/ja/manage-claude/usage-cost-analytics-api)はどちらも、ユーザープロファイルごとの使用量を報告します。どちらも、あなたが支払うリクエストと顧客が支払うリクエストの両方をカウントします。どちらも、顧客が支払った金額や顧客の料金は表示しません。

Consoleでは、[User profiles](https://platform.claude.com/user-profiles)ページに、過去28日間の各ユーザープロファイルの**Requests**、**Tokens**、および**Your spend**が一覧表示されます。顧客が支払うリクエストは、プロファイルの**Requests**と**Tokens**に加算され、**Your spend**には何も加算されません。

APIは、`org:admin`スコープを持つOAuthアクセストークンやAdmin APIキーなどの[Admin APIの認証情報](https://platform.claude.com/docs/ja/manage-claude/admin-api#authentication)で呼び出してください。オペレーターサービスアカウント（ステップ3）は使用しないでください。そのフェデレーションルールは、デフォルトで`org:admin`ではなく`workspace:developer`を付与します。`org:admin`スコープはAdmin API全体を対象とするため、オペレーターサービスアカウントには追加しないでください。

APIを通じてユーザープロファイルごとに報告するには、その[使用量エンドポイント](https://platform.claude.com/docs/ja/manage-claude/usage-cost-analytics-api#usage-endpoint)または[コストエンドポイント](https://platform.claude.com/docs/ja/manage-claude/usage-cost-analytics-api#cost-endpoint)を呼び出します。ユーザープロファイルごとに1行を取得するには、`user_profile_id`のみでグループ化し、`time_bucket_width`を省略します。行が返されるのは、リクエストした期間内に使用量があるユーザープロファイルのみです。さらに1行、`user_profile_id`がnullの行があります。この行には、プロファイルを指定しなかった使用量と、コード実行コンテナの時間など、リクエストの外で計測される使用量が含まれます。

コストエンドポイントでは、顧客が支払うリクエストは、`amount`に0を、`list_amount`にその定価を加算します。`amount`フィールドは**Your spend**と同じ尺度です。APIには、誰が支払ったかを示すフィールド、フィルター、または`group_by[]`の値はありません。`amount`が0で`list_amount`が0より大きい行は、通常、その行のすべてのリクエストを顧客が支払ったことを意味します。

これらの数値を使用して、あなたが選択した金額で顧客の使用を停止しないでください。ConsoleもAPIもリアルタイムでは報告しません。Consoleの数値は約1時間に1回更新され、リクエストが表示されるまでに数時間かかることがあります。APIの遅延については、[データの鮮度](https://platform.claude.com/docs/ja/manage-claude/usage-cost-analytics-api#data-freshness)を参照してください。顧客自身の制限がどのように機能するかについては、[支出上限](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#spend-caps)を参照してください。

### 顧客のリンクを解除する

Consoleで顧客のリンクを解除するには、[User profilesページ](https://platform.claude.com/user-profiles)のリスト、またはユーザープロファイルの詳細ページ右上にある**Unlink**ボタンを使用します。

バックエンドから顧客のリンクを解除するには、ステップ8で保存した接続IDを、コード交換と同じクライアント認証を使用して[取り消しエンドポイント](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/oauth-reference#revocation)に送信します。代わりにユーザープロファイルで接続を指定するには、`connection_id`の代わりに`user_profile_id`を送信します。

<CodeGroup exclude="shell:CLI">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/revoke \
    -H "content-type: application/json" \
    -d @- <<'JSON'
  {
    "connection_id": "ocon_01HV9Z",
    "client_id": "YOUR_CLIENT_ID",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
  }
  JSON
  ```

  ```python Python
  def revoke_connection(connection_id: str) -> list[str]:
      response = httpx.post(
          f"{AUTH}/v1/oauth/revoke",
          json={
              "connection_id": connection_id,
              "client_id": CLIENT_ID,
              "client_assertion_type": JWT_BEARER,
              "client_assertion": client_assertion(),
          },
      )
      response.raise_for_status()
      # このリクエストで終了した接続の ID。接続がすでに終了していた場合、
      # または ID が不明な場合、リストは空になります。
      return response.json()["revoked_connection_ids"]
  ```

  ```typescript TypeScript
  // auth.claude.com に対応する SDK はないため、この例では直接呼び出します。
  import { readFile } from "node:fs/promises";

  // ステップ 8 で保存した接続 ID です。
  const connectionId = "ocon_01HV9Z";

  // クライアントアサーション: ID トークンファイル内の JWT です。ファイルはローテーションされるため、リクエストごとに読み込みます。
  // アプリのクライアント認証がその JWT とは異なる audience を想定している場合は、2 つ目のトークンファイルを使用します。
  const clientAssertion = (
    await readFile(process.env.ANTHROPIC_IDENTITY_TOKEN_FILE!, "utf8")
  ).trim();

  const response = await fetch("https://auth.claude.com/v1/oauth/revoke", {
    method: "POST",
    redirect: "error",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      connection_id: connectionId,
      client_id: "YOUR_CLIENT_ID",
      client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      client_assertion: clientAssertion
    })
  });
  if (!response.ok) {
    throw new Error(`revoke failed: ${response.status}`);
  }

  const { revoked_connection_ids: revokedConnectionIds } = (await response.json()) as {
    revoked_connection_ids: string[];
  };
  console.log(revokedConnectionIds); // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  ```

  ```csharp C#
  // auth.claude.com に対応するSDKはないため、この例では直接呼び出します。
  using System.Net.Http.Json;
  using System.Text.Json;

  // ステップ8で保存した接続IDです。
  var connectionId = "ocon_01HV9Z";

  // クライアントアサーション：IDトークンファイル内のJWTです。ファイルはローテーションされるため、リクエストごとに読み込みます。
  // アプリのクライアント認証がそのJWTと異なるaudienceを想定している場合は、2つ目のトークンファイルを使用します。
  var tokenFile = Environment.GetEnvironmentVariable("ANTHROPIC_IDENTITY_TOKEN_FILE")!;
  var clientAssertion = (await File.ReadAllTextAsync(tokenFile)).Trim();

  using var http = new HttpClient();
  using var response = await http.PostAsJsonAsync(
      "https://auth.claude.com/v1/oauth/revoke",
      new Dictionary<string, string>
      {
          ["connection_id"] = connectionId,
          ["client_id"] = "YOUR_CLIENT_ID",
          ["client_assertion_type"] = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
          ["client_assertion"] = clientAssertion,
      }
  );
  response.EnsureSuccessStatusCode();

  var result = await response.Content.ReadFromJsonAsync<JsonElement>();
  Console.WriteLine(result.GetProperty("revoked_connection_ids")); // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  ```

  ```go Go
  // auth.claude.com に対応するSDKはないため、この例では直接呼び出します。

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"net/http"
  	"os"
  	"strings"
  )

  func main() {
  	// ステップ8で保存した接続ID。
  	connectionID := "ocon_01HV9Z"

  	// クライアントアサーション：IDトークンファイル内のJWTです。ファイルはローテーションされるため、リクエストごとに読み込みます。
  	// アプリのクライアント認証がそのJWTと異なるaudienceを想定している場合は、2つ目のトークンファイルを使用します。
  	token, err := os.ReadFile(os.Getenv("ANTHROPIC_IDENTITY_TOKEN_FILE"))
  	if err != nil {
  		panic(err)
  	}

  	body, err := json.Marshal(map[string]string{
  		"connection_id":         connectionID,
  		"client_id":             "YOUR_CLIENT_ID",
  		"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  		"client_assertion":      strings.TrimSpace(string(token)),
  	})
  	if err != nil {
  		panic(err)
  	}

  	response, err := http.Post("https://auth.claude.com/v1/oauth/revoke", "application/json", bytes.NewReader(body))
  	if err != nil {
  		panic(err)
  	}
  	defer response.Body.Close()
  	if response.StatusCode < 200 || response.StatusCode > 299 {
  		panic(fmt.Sprintf("revoke failed: %d", response.StatusCode))
  	}

  	var result struct {
  		RevokedConnectionIDs []string `json:"revoked_connection_ids"`
  	}
  	if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
  		panic(err)
  	}
  	fmt.Println(result.RevokedConnectionIDs) // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  }
  ```

  ```java Java
  // auth.claude.com に対応する SDK はないため、この例では直接呼び出します。Java SDK には Jackson が含まれています。
  import com.fasterxml.jackson.databind.ObjectMapper;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.nio.file.Files;
  import java.nio.file.Path;

  void main() throws Exception {
      // ステップ 8 で保存した接続 ID です。
      String connectionId = "ocon_01HV9Z";

      // クライアントアサーション：ID トークンファイル内の JWT です。ファイルはローテーションされるため、リクエストごとに読み込みます。
      // アプリのクライアント認証が、その JWT とは異なる audience を想定している場合は、2 つ目のトークンファイルを使用します。
      String clientAssertion = Files.readString(
          Path.of(System.getenv("ANTHROPIC_IDENTITY_TOKEN_FILE"))).strip();

      var mapper = new ObjectMapper();
      String body = mapper.createObjectNode()
          .put("connection_id", connectionId)
          .put("client_id", "YOUR_CLIENT_ID")
          .put("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer")
          .put("client_assertion", clientAssertion)
          .toString();

      var request = HttpRequest.newBuilder(URI.create("https://auth.claude.com/v1/oauth/revoke"))
          .header("content-type", "application/json")
          .POST(HttpRequest.BodyPublishers.ofString(body))
          .build();
      var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
      if (response.statusCode() / 100 != 2) {
          throw new IllegalStateException("revoke failed: " + response.statusCode());
      }

      // このリクエストによって終了した接続の ID です。接続がすでに終了していた場合や ID が不明な場合、リストは空になります。
      IO.println(mapper.readTree(response.body()).get("revoked_connection_ids"));
  }
  ```

  ```php PHP
  // auth.claude.com に対応する SDK はないため、この例では直接呼び出します。

  // Step 8 で保存した接続 ID です。
  $connectionId = 'ocon_01HV9Z';

  // クライアントアサーション: ID トークンファイル内の JWT です。ファイルはローテーションされるため、リクエストごとに読み込みます。
  // アプリのクライアント認証がその JWT と異なる audience を想定している場合は、2 つ目のトークンファイルを使用します。
  $clientAssertion = trim(
      file_get_contents((string) getenv('ANTHROPIC_IDENTITY_TOKEN_FILE'))
          ?: throw new \RuntimeException('the file named by ANTHROPIC_IDENTITY_TOKEN_FILE cannot be read or is empty')
  );

  $body = json_encode([
      'connection_id' => $connectionId,
      'client_id' => 'YOUR_CLIENT_ID',
      'client_assertion_type' => 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
      'client_assertion' => $clientAssertion,
  ], JSON_THROW_ON_ERROR);

  $context = stream_context_create(['http' => [
      'method' => 'POST',
      'header' => 'content-type: application/json',
      'content' => $body,
  ]]);
  $response = file_get_contents('https://auth.claude.com/v1/oauth/revoke', context: $context);
  if ($response === false) {
      throw new \RuntimeException('revoke failed');
  }

  /** @var array{revoked_connection_ids: list<string>} $result */
  $result = json_decode($response, associative: true, flags: JSON_THROW_ON_ERROR);
  // このリクエストで終了した接続の ID です。接続がすでに終了していたか ID が不明な場合、リストは空になります。
  echo implode(', ', $result['revoked_connection_ids']), PHP_EOL;
  ```

  ```ruby Ruby
  # auth.claude.com に対応する SDK はないため、この例では直接呼び出します。
  require "json"
  require "net/http"

  # Step 8 で保存した接続 ID です。
  connection_id = "ocon_01HV9Z"

  # クライアントアサーション：ID トークンファイル内の JWT です。ファイルはローテーションされるため、リクエストごとに読み込みます。
  # アプリのクライアント認証がその JWT と異なる audience を想定している場合は、2 つ目のトークンファイルを使用します。
  client_assertion = File.read(ENV.fetch("ANTHROPIC_IDENTITY_TOKEN_FILE")).strip

  response = Net::HTTP.post(
    URI("https://auth.claude.com/v1/oauth/revoke"),
    {
      connection_id: connection_id,
      client_id: "YOUR_CLIENT_ID",
      client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      client_assertion: client_assertion
    }.to_json,
    "content-type" => "application/json"
  )
  response.value # raises on an error

  # このリクエストで終了した接続の ID です。接続がすでに終了していたか ID が不明な場合、リストは空になります。
  puts(JSON.parse(response.body).fetch("revoked_connection_ids"))
  ```
</CodeGroup>

`auth.claude.com`は、HTTP 200と、このリクエストによって終了した接続のIDである`revoked_connection_ids`を返します。接続がすでに終了している場合、リストは空になるため、`connection_id`を送信するリクエストは安全に繰り返すことができます。IDが不明な場合もリストは空になるため、空のリストは接続が存在したことを証明するものではありません。その他のパラメータについては[取り消し](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/oauth-reference#revocation)を、エラーについては[取り消しエンドポイントからのエラー](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/oauth-reference#errors-from-the-revocation-endpoint)を参照してください。

接続が終了すると、ユーザープロファイルは**Unlinked**と表示され、この顧客に対して`bill_to: "user_profile"`を設定したリクエストは`user_profile_not_billable`を受け取ります。`bill_to: "self"`を指定することで、引き続き自己負担で顧客にサービスを提供できます。顧客側の表示については[リンク後](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#after-connecting)を、どの方法でリンクを解除すると顧客にメールが送信されるかについては[リンクとリンク解除に関するメール](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#emails-to-your-customer)を参照してください。

### 顧客を別のClaude組織にリンクする

顧客のユーザープロファイルを別のClaude組織にリンクするには、顧客のリンクを解除してから、再度リンクします。

リンクを解除した後は、この顧客に請求するリクエストは拒否されます。これは、ユーザーが別の組織について承認し、あなたがステップ8でコードを交換するまで続きます。そのユーザーが承認する準備ができたら、以下の手順に従ってください：

1. 顧客がすでに自身の[Linked platforms](https://platform.claude.com/linked-platforms)ページでアプリのリンクを解除している場合は、このステップをスキップしてください。それ以外の場合は、[顧客のリンクを解除する](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer)の説明に従って顧客のリンクを解除します。その後、ユーザープロファイルは[User profiles](https://platform.claude.com/user-profiles)ページで**Unlinked**と表示されます。
2. 同じユーザープロファイルを使用して、[ステップ5から8](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#runtime-step-2)を再度実行します。[ステップ7](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#the-administrator-approves)では、ユーザーは別の組織で管理者または請求のロールを持つアカウントが必要です。ユーザーにその組織について承認してもらってください。
3. 新しい接続IDを以前のものの代わりに保存します。接続のトークンを使用している場合は、新しいトークンについても同様にしてください。

顧客のリンクが解除されるまで、承認ページでは、すでにリンクされている組織についてのみ承認できます。

支出上限は1つの顧客組織とあなたのアプリに属するため、最初の組織の上限は引き継がれません。ルールについては[支出上限](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#spend-caps)を参照してください。

## 想定されるエラー

リクエストで`bill_to: "user_profile"`を設定した場合、Anthropicは顧客に請求するか、リクエストを拒否するかのいずれかです。代わりにあなたに暗黙的に請求することはありません。`/v1/messages`では、以下のリストのコードは`error.details.error_code`に含まれます。`/v1/chat/completions`では、コードなしで、同じHTTPステータスとメッセージがOpenAI形式で返されます：

* `403 permission_error, user_profile_not_billable`：Anthropicはこのリクエストについてこの顧客に請求できず、レスポンスには理由は示されません。新しい接続後の最初の10秒間を除き、再試行できません。顧客に再度リンクするよう依頼する前に、[`user_profile_not_billable`の原因](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable)を参照してください。再リンクで解決するのはその一部のみです。`bill_to: "self"`を指定して再送信することで、引き続き自己負担で顧客にサービスを提供できます。Anthropic SDKでは、403ステータスの[エラークラス](https://platform.claude.com/docs/ja/api/errors#sdk-error-types)である`PermissionDeniedError` (java, php: `PermissionDeniedException`; csharp: `AnthropicForbiddenException`; go: `apierr.StatusCode == http.StatusForbidden`)によって`user_profile_not_billable`を処理します。これは他の403エラーにも一致するため、エラーコードも確認してください。

* `402 billing_error, linked_organization_billing_unavailable`：Anthropicは現在、顧客の組織に請求できません（たとえば、組織が停止されている、またはClaudeが応答を開始した後にクレジットが尽きた場合）。レスポンスには理由は示されません。リクエストが届いた時点でクレジットがない顧客には、代わりに`linked_organization_spend_limit_reached`が返されます。再試行できません。顧客にClaude Platformアカウントを確認するよう伝えてください。`bill_to: "self"`を指定して再送信することで、引き続き自己負担で顧客にサービスを提供できます。

* `402 billing_error, linked_organization_spend_limit_reached`：顧客の組織が自ら設定した支出制限に達しました。これは、アプリに適用される[支出上限](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#spend-caps)、または組織全体の月間支出制限のいずれかです。組織にリクエストの支払いに充てられるクレジットがない場合にも、Claude APIは同じコードを送信します。レスポンスにはどちらであるかは示されません。リクエストはClaudeが応答を開始する前に拒否されました。再試行できません。`bill_to: "self"`を指定して再送信することで、引き続き自己負担で顧客にサービスを提供できます。Claude Consoleで以下を確認するよう顧客に依頼してください：

  * **アプリの支出上限：** 顧客は、[Linked platforms](https://platform.claude.com/linked-platforms)にあるアプリのページで支出上限を設定または引き上げることができます。そこで設定した上限は、すべてのリンク済みプラットフォームに対して設定したデフォルトの上限を置き換えます。
  * **組織の月間支出上限：** [支出上限](https://platform.claude.com/settings/billing#spend-limits)で引き上げることができます。
  * **クレジット残高：** [請求](https://platform.claude.com/settings/billing)ページで、クレジット残高を確認し、クレジットを購入できます。一部のクレジットはこれらのリクエストの支払いに使用できません。[支払いに使用できるクレジット](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#which-credits-can-pay)を参照してください。

* `503 overloaded_error`：Anthropicは現時点で顧客に請求できるかどうかを確認できませんでした。バックオフを用いて再試行し、`retry-after`ヘッダーに従ってください。リクエストは処理されておらず、請求もされていません。

* `400 invalid_request_error, user_profile_required`：`anthropic-user-profile-id`ヘッダーなしで`bill_to: "user_profile"`を設定しました。このようなリクエストには、接続のアクセストークンを使用し、かつヘッダーが任意である場合を除き、ヘッダーが必要です。ヘッダーが任意かどうかを確認するには、[接続のアクセストークンでClaudeを呼び出す](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token)の注記を参照してください。

* `400 invalid_request_error`（エラーコードなし）：`anthropic-user-profile-id`ヘッダーに、形式が不正なID、またはあなたの組織のユーザープロファイルではないIDが含まれています。

* `400 invalid_request_error`（エラーコードなし）：リクエストが接続のアクセストークンで認証され、`bill_to: "self"`を設定したか、トークンが限定されているユーザープロファイル以外のユーザープロファイルを指定しました。[接続のアクセストークンでClaudeを呼び出す](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token)を参照してください。

`/v1/messages`と`/v1/chat/completions`では、接続のアクセストークンを使用してあなたが支払うリクエストを送信することはできません。拒否されたリクエストを`bill_to: "self"`を指定して再送信するには、自身のバックエンドから、オペレーターサービスアカウント自身の認証情報で認証してください。トークン自体に対する拒否については、[接続のアクセストークンでClaudeを呼び出す](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token)に記載されています。

成功したレスポンスには誰に請求されたかが示されないため、どのリクエストを`bill_to: "user_profile"`で送信したかを独自に記録しておいてください。

### `user_profile_not_billable`の原因

以下の順に確認してください：

* **リクエスト。** リクエストは、OAuthアプリのオペレーターサービスアカウント（ステップ3）として認証する必要があります。[接続のアクセストークン](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection)も、そのサービスアカウントとして認証します。それ以外の方法で認証したリクエストは拒否されます。たとえば、別のサービスアカウントや、そのサービスアカウントに紐付けられていないAPIキーです。`anthropic-user-profile-id`ヘッダーが、リンクされていないあなたのプロファイルのいずれかを指定している場合、リクエストは拒否されます。認証情報またはヘッダーが誤っている場合は、リクエストを修正してください。新しい接続では解決しません。
* **接続。** 顧客がこのアプリを通じてリンクしていないか、接続が終了しています。顧客の組織またはあなたの組織の管理者が接続を終了したか、あなたのバックエンドが終了しました。終了した接続は、[User profiles](https://platform.claude.com/user-profiles)ページで**Unlinked**と表示されます。テストアプリを通じてのみリンクされたプロファイルは、本番アプリにはリンクされていません。顧客がリンクするまで、その顧客への請求を停止してください。接続のアクセストークンはその接続に限定されるため、顧客が再度リンクした後は、新しい接続のアクセストークンを使用してください。アプリで[オペレーターのみの認証をオフにしている](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication)場合、顧客に請求できるのは、その顧客の接続のアクセストークンを使用する場合のみです。その場合、`billing:attribution`接続の有効なトークンを保持していない顧客は、**Linked**と表示されていても、[顧客を再度リンクする](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again)の説明に従って再度承認する必要があります。
* **顧客の組織。** [対象となる顧客](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints)である必要があります。これはあなたの側からは確認できないため、Anthropicのアカウントチームに問い合わせてください。

新しい接続は通常すぐに機能しますが、ステップ8の交換後、約10秒かかる場合があります。その10秒間にリクエストが`user_profile_not_billable`で拒否された場合は、再度送信してください。それ以降は、待機しても再試行しても結果は変わりません。拒否された各リクエストについて、`error.message`全体と`request-id`レスポンスヘッダーをログに記録してください。接続が**Linked**と表示されている顧客が引き続き拒否され、リクエストが正しい場合は、拒否された理由をAnthropicが調べられるよう、拒否されたリクエストの`request-id`をAnthropicのアカウントチームに送信してください。

## 顧客側の表示

### リンク

ステップ6でアプリがユーザーをリダイレクトした後、ユーザーは`auth.claude.com`で承認します。[ステップ7](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#the-administrator-approves)に承認ページの画面が一覧表示されています。各画面にはアプリの名前が表示され、**Cancel**ボタンがあります。各画面でユーザーが行うことは次のとおりです：

* **Select an organization：** ユーザーは、自身のClaude組織のうちどれをリンクするかを選択します。この画面は、ユーザーが組織を選択できる場合にのみ表示されます。
* **How billing works：** ユーザーは画面を読み、**Continue**をクリックします。
* **Set a monthly spend limit：** ユーザーは、あなたのアプリの上限を米ドルの整数単位で入力して**Continue**をクリックします。金額フィールドは空の状態で始まるため、ページがユーザーの代わりに上限を選択することはありません。**Continue without a limit**を選択すると新しい上限は保存されず、顧客が以前に保存した上限またはデフォルトが引き続き適用されます。ユーザーが入力する上限は、[支出上限](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#spend-caps)で説明されている支出上限です。アプリがテスト中の間は、この画面が異なります。[アプリのテスト中](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#while-your-app-is-in-testing)を参照してください。
* **最後の画面：** この画面には、ユーザーが選択した上限を含め、あなたのアプリが実行できることが一覧表示されます。ユーザーは**Link and authorize**をクリックします。

承認ページは、ブラウザでサインインしているClaudeアカウントを使用し、そのアカウントのClaude組織のみを提示します。これは、ユーザーが想定しているアカウントではない可能性があります（たとえば、仕事用ではなく個人用のアカウントなど）。アプリがアカウントを選択することはできません。OpenID Connectのパラメータ`prompt=select_account`と`login_hint`は、ページが使用するアカウントを変更しません。

### リンク後

顧客は、Claude Consoleの[Linked platforms](https://platform.claude.com/linked-platforms)ページで接続を管理します。顧客はいつでもアプリのリンクを解除できます。解除されても、Anthropicはあなたに通知しません。webhookイベントもメールも届きません。

顧客がリンクを解除した後、その顧客に請求するリクエストは403 `user_profile_not_billable`で拒否されます（[`user_profile_not_billable`の原因](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable)を参照）。Consoleの[User profiles](https://platform.claude.com/user-profiles)ページでは、その顧客のユーザープロファイルが**Unlinked**と表示されます。再度リンクするには、顧客の既存のユーザープロファイルを使用して[ステップ5から8](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#runtime-step-2)を再度実行してください。

### リンクとリンク解除に関するメール

リンクとリンク解除に関するAnthropicのメールは、顧客の組織で管理者または請求のロールを持つメンバーに送信されます。各メールには、顧客のLinked platformsページへのリンクが含まれます。Anthropicがメールを送信するかどうかは、イベントによって異なります：

* **顧客がアプリをリンクしたとき：** あなたがステップ8でコードを交換した時点で、Anthropicはメールを送信します。コードが交換されなかった承認については、何も送信しません。また、顧客がまだリンクされている間にユーザーが再度承認した場合も、何も送信しません。
* **顧客がアプリのリンクを解除したとき：** Anthropicはメールを送信します。メールには、アプリのリンクを解除した人の名前は記載されません。
* **あなたがバックエンドから顧客のリンクを解除したとき：** Anthropicはメールを送信します。
* **あなたがConsoleで顧客のリンクを解除したとき：** Anthropicはメールを送信しません。

Anthropicは、メールが送信または配信されることを保証しません。顧客のリンクを解除する場合は、あなた自身から顧客に伝えてください。顧客にリンクされていることを伝える手段として、これらのメールに依存しないでください。

### 支出上限

顧客は、アプリに対する月間の支出上限を米ドル（USD）で設定できます。承認ページではこの上限を月間支出制限と呼んでおり、リンクするユーザーはそこで上限を設定できます（[リンク](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#connecting)を参照）。これは、組織全体に適用される組織の**月間支出上限**とは別のものです。顧客の上限や、そのうちどれだけが使用されたかを読み取ることはできません。

アプリを通じた顧客の支出が上限に達すると、Claude APIは顧客に請求するリクエストを402で拒否します。[想定されるエラー](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#expected-errors)を参照してください。拒否は、翌月1日の00:00 UTCまで、または顧客が上限を引き上げるか削除するまで続きます。上限の変更が反映されるまでに約1分かかることがあります。

リンク後は、管理者または請求のロールを持つ顧客の組織のメンバーが、Consoleの[Linked platforms](https://platform.claude.com/linked-platforms)ページで上限を管理します：

* **上限を設定または変更する：** アプリをクリックし、**Set spend cap**または**Edit spend cap**をクリックします。
* **デフォルトを設定する：** **Default spend cap**の下で、**Set default**または**Edit**をクリックします。独自の上限を持たない各リンク済みアプリは、毎月デフォルトの金額まで支出できます。アプリ間でデフォルトを共有することはありません。
* **上限を削除する：** アプリをクリックし、**Edit spend cap**、次に**Remove cap**をクリックします。その後、アプリにはデフォルトが適用されます。デフォルトがない場合は上限なしになります。

最小の上限は0米ドルで、その場合、その顧客に請求するすべてのリクエストが拒否されます。Consoleではドル単位の整数を入力でき、実質的な最大値はありません。上限では、トークンのコストとウェブ検索の料金が、交渉による割引適用前の定価で計算されます。顧客の請求額は、上限で計算される金額と異なる場合があります。

上限は、顧客が[支出上限](https://platform.claude.com/settings/billing#spend-limits)で設定する組織の**月間支出上限**より高く設定できます。Claude APIは、どちらか一方に達した時点で、顧客に請求するリクエストを拒否します。

#### アプリのテスト中

アプリがテスト中、審査中、または未承認の間に誰かがアプリをリンクするか、その上限を変更する場合は、常に以下の制限が適用されます：

|                                    | テスト中、審査中、または未承認 | アプリの公開後   |
| ---------------------------------- | --------------- | --------- |
| 承認ページでの月間支出制限                      | 必須、50米ドル以下      | 任意        |
| 承認ページの金額フィールド                      | 50米ドルから始まる      | 空の状態で始まる  |
| 承認ページの**Continue without a limit** | 提供されない          | 提供される     |
| Consoleでの上限の削除                     | 不可              | 可能        |
| 顧客が設定できる最大の上限                      | 50米ドル           | 実質的な最大値なし |

アプリが公開されると、それ以前に顧客が保存した上限はそのまま維持されます。その後、顧客はそれを引き上げたり削除したりできます。

### 顧客のサポート

顧客に請求するClaudeの使用量を含め、アプリに関するすべての事項について顧客をサポートするのはあなたです。Anthropicは顧客に承認ページと、Claude ConsoleのLinked platformsページを提供しています。Linked platformsページでは、管理者または請求のロールを持つメンバーが、今月アプリによって組織にかかった費用を確認できます。また、アプリに月間の[支出上限](https://platform.claude.com/docs/ja/manage-claude/oauth-apps/organization-billing-connections#spend-caps)を設定したり、アプリのリンクを解除したりすることもできます。アプリに関するその他のすべての質問はあなたに寄せられるべきものですので、顧客にあなたへの連絡方法を伝えてください。

## コードスニペットの初期化

このページのPythonの例は、以下の共通のセットアップを使用しており、これは一度だけ記述します。以下を定義します：

* インポート
* アプリのクライアントIDとリダイレクトURI
* 請求ベータヘッダーの値
* サービスアカウントとして認証するClaude APIクライアント
* `client_assertion`。バックエンドが`auth.claude.com`に送信するクライアントアサーションを返します

```python
# Python の例では、以下の初期化と変数を前提としています
import secrets
from urllib.parse import urlencode

import anthropic
import httpx
from anthropic.lib.credentials import IdentityTokenFile
from anthropic.types import Message
from anthropic.types.beta import BetaMessage
from authlib.oauth2.rfc7636 import create_s256_code_challenge

AUTH = "https://auth.claude.com"
# OAuth アプリを登録した後、platform.claude.com からコピーします。
CLIENT_ID = "YOUR_CLIENT_ID"
REDIRECT_URI = "https://app.example.com/claude/billing/callback"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
BILLING_BETA = "user-profiles-billing-2026-10-01"

# API クライアント。SDK はワークロードの ID JWT をアクセストークンと交換し、
# 更新も行うため、"Bearer <access token>" を自分で扱う必要はありません。
client = anthropic.Anthropic()

# auth.claude.com 用のクライアントアサーション: ID JWT そのもので、ファイルがローテーションされるため
# 呼び出しごとに新たに読み込みます。アプリのクライアント認証設定で
# フェデレーションルールと異なる audience を指定している場合は、これを
# 2 つ目のトークンファイルに向けます: IdentityTokenFile("/path/to/other/token")。
client_assertion = IdentityTokenFile()
```
