# Provisioning API をプラットフォームに実装する

プラットフォームのバックエンドから Provisioning API を使用して、プロバイダーの接続、リソースのプロビジョニング、承認済みテナント向けの有料サービスの管理を行います。

> The Provisioning API is allowlisted during private preview. Contact your Stripe representative or email [provisioning-preview@stripe.com](mailto:provisioning-preview@stripe.com) for access.
> 
> During private preview, send the preview API version **2026-09-30.preview** in the `Stripe-Version` header. The API contract can change during the preview. Confirm the enabled request and response contract for your cohort before deployment, tolerate new response fields, and use returned enum values instead of assuming wire spellings.

このフローでは、プラットフォームの Stripe キーを使用して認証し、`Stripe-Context` を使用して承認済みの連結アカウントの代理として操作します。このガイドでは、直接アカウントの実装については取り扱いません。

## はじめに

コードを記述する前に、各リクエストを実行するアカウントを特定し、Stripe が Provisioning オブジェクトのスコープをどのように設定しているかを理解した上で、Stripe 側で有効化されている機能を確認してください。以下のセクションでは、アカウントモデル、オブジェクトのスコープと関係性、および初回の書き込みリクエストの実行前に完了しておくべき確認事項について説明します。

### 正しいアカウントモデルを使用する

決済手段の登録や、ユーザー向け有料リソースのプロビジョニングを行う前に、これらの設定手順を完了してください。

| アクターまたはオブジェクト | 役割 |
| --- | --- |
| プラットフォームアカウント | 承認済みの制限付きキー、または必要に応じてプラットフォームのシークレットキーを使用して API コールを認証します。 |
| プラットフォームテナント | ワークスペースや組織など、永続的な承認の境界です。 |
| 連結アカウント | プロジェクト、プロバイダー接続、リソース、決済プロファイル、認証情報、および利用状況を保有する Stripe アカウントです。 |
| アプリケーション環境 | プレビューや本番環境などのデプロイの境界です。 |
| プラットフォームのバックエンド | 認証済みユーザーを特定のテナントと連結アカウントに紐付けて、Stripe の呼び出し、状態の永続化、シークレットの管理を行います。 |
| プロバイダー | サービスを公開し、その基盤となるインフラストラクチャを所有するサードパーティーです。 |

各 `tenant_id` からそれに対応する `connected_account_id` への検証済みマッピングを保存し、そのマッピングを使用して連結アカウントを紐付けます。ブラウザーからのリクエスト、モデルのプロンプト、URL パラメーター、または生成されたアプリケーションから受け取った連結アカウント ID を、そのまま Stripe に渡さないでください。

Provisioning API への認証済みリクエストには、常に以下の値を含めてください。

```
Authorization: Bearer {{PLATFORM_SECRET_OR_RESTRICTED_KEY}}
Stripe-Context: {{CONNECTED_ACCOUNT_ID}}
Stripe-Version: 2026-09-30.preview
Content-Type: application/json
```

バックエンドで `Stripe-Context` を追加する前に、ユーザーがそのテナントと連結アカウントへのアクセス権限を持っていることを確認します。ブラウザー、生成されたアプリケーション、またはコーディングエージェントが Provisioning API を直接呼び出せないようにしてください。

### スコープとトポロジーをマッピングする

Provisioning オブジェクトにはそれぞれ異なるスコープがあります。サービスのスコープによって、それを共有できる範囲が決まります。

1 つの連結アカウントを含むプラットフォームテナントを示す図。この連結アカウントは、アカウントスコープのプロバイダー接続、アカウントスコープのプランリソース、およびそれぞれがプロジェクトスコープのリソースを保持する 2 つのプロジェクトを所有しています。 (See full diagram at https://docs.stripe.com/provisioning)

```text
[プラットフォームテナントまたはワークスペース] --> [連結アカウント]
[連結アカウント] --> [プロバイダー接続: モデルゲートウェイ (アカウントスコープ)]
[連結アカウント] --> [プランリソース: データベースプラン (アカウントスコープ)]
[連結アカウント] --> [プロジェクト: App A 本番環境]
[連結アカウント] --> [プロジェクト: App B 本番環境]
[プロジェクト: App A 本番環境] --> [リソース: App A データベース (プロジェクトスコープ)]
[プロジェクト: App B 本番環境] --> [リソース: App B データベース (プロジェクトスコープ)]
```

- Provisioning プロジェクトは CLI 環境とは異なります。CLI 環境はローカルの CLI 設定や出力を保存するのに対し、プロジェクトは Provisioning のグループ化と認証情報の境界を定義します。
- プロバイダー接続はアカウントスコープで作成します。1 つの接続で連結アカウント内のすべてのプロジェクトがサポートされるため、アプリケーションごとに個別の接続を作成しないでください。
- 各サービスに対して返された `scope` を使用します。プロバイダー、サービス名、または意図した用途からスコープを推測しないでください。
- プランを含むアカウントスコープのリソースをプロジェクトに関連付けることができます。この関連付けによってリソースのスコープが変わることはありません。
- 返されたスコープと依存関係の仕様を通じてカタログのレスポンスで許可されている場合に限り、複数のプロジェクトやアプリケーションにまたがる依存リソースに対して 1 つのプランを使用できます。レスポンスに含まれる両方の値を確認してください。

### プライベートプレビューに登録する

本番環境向けの実装を行う前に、プレビュー所有者と以下の項目を確認してください。

- プラットフォームとテスト用の連結アカウントがコホートに登録されていること。
- コホートに対して、Provisioning API と Accounts API の両方でプレビュー API バージョンが有効になっていること。
- 承認済みの連結アカウント設定とアカウント登録手順が定義されていること。
- 対象となるプロバイダーとカタログパーティションが定義されていること。
- 該当する場合、有料テストのプロビジョニングとプラットフォーム所有の決済ソースが有効になっていること。

Provisioning API によってプラットフォームの登録や連結アカウント関係の作成が自動的に行われることはありません。プライベートプレビューへの登録は、Stripe 担当者のサポートによる許可リストへの追加手続きとなります。コホートが明示的に承認している Accounts API の設定と、ホスト型のアカウント登録フローを使用します。

### プレフライトチェックリストを完了する

最初の Provisioning 書き込みを実行する前に、以下のステップを順番に実行してください。いずれかのステップを完了できない場合は、回避策を講じずに処理を中断し、プレビュー所有者とともに解決します。

1. プラットフォームアカウント、対象の連結アカウント、およびカタログと決済コホートが許可リストに登録されていることを確認します。
2. 有効化されている `Stripe-Version` を記録し、それとは別にコホートで必要とされる Accounts API の設定を記録します。これらは 2 つの独立した仕様であり、一方を有効化しても他方が有効化されるわけではありません。
3. コホートにおいて、カタログの読み取り、無料プロビジョニング、および有料プロビジョニングをサポートしている環境を確認します。
4. 連結アカウントのコンテキストで利用資格を確認します。
5. 有料サービスを設定する前に、無料のリソースを 1 つエンドツーエンドでプロビジョニングします。

利用資格、カタログの利用可否、連結アカウントのアカウント登録は、それぞれ独立した 3 つのゲートです。カタログの読み取りに成功しても、それはカタログが読み取り可能であることのみを証明するものです。連結アカウントのアカウント登録が完了していることや、アカウントが利用資格を満たしていること、あるいはいずれかの書き込みパスが機能することを証明するものではありません。

## バックエンドを構築する

最初の API リクエストを実行する前に、次の 2 つのコンポーネントを実装します。以降の番号付きステップに含まれるすべてのリクエストは、両方のコンポーネントを経由してルーティングします。

### バックエンドアダプターを作成する

すべての呼び出しはプラットフォームのバックエンドを経由して実行されます。アダプターで以下の処理を行う必要があります。

- 45 秒以下のネットワークタイムアウトを設定します。
- 返された `next_page_url` と `previous_page_url` に従います。不透明な `page` 値を独自に構築しないでください。
- リストの取得結果は、非推奨のエイリアス (`providers`、`services`、`resources` など) からではなく、`data` から読み取ります。
- 書き込みリクエストを送信する前に、実行予定の書き込み内容を永続化します。
- シークレット以外のリクエスト ID、オブジェクト ID、ステータス遷移、エンドポイント名またはアクション名、HTTP ステータス、エラーコードを保存します。
- `request_log_url` は信頼できる復旧パスとしてではなく、補足的な診断データとして扱います。
- 認証情報、アクセス設定、コールバックシークレット、決済情報、事前認証済み URL は、ログ、ブラウザーのレスポンス、分析データ、サポートチケット、モデルプロンプトから非表示にします。

このプレビューでは、状態を変更する操作に対して、呼び出し側による冪等性制御やリクエストの関連付け機能は提供されません。書き込みリクエストの結果を受信できなかった場合に復旧できるよう、アダプターを設計します。各書き込みリクエストを送信する前に、結果が不明となった場合でも照合して復旧できるよう、意図した変更内容を永続化しまい。

### プラットフォームの状態をモデル化する

少なくとも、以下を確実に保存します。

```
Tenant
  tenant_id
  connected_account_id

Application environment
  application_id
  environment
  project_id

Provisioning workflow
  workflow_id
  tenant_id
  connected_account_id
  action
  provider_id
  service_ref
  provider_connection_request_id
  provider_connection_id
  resource_id
  status
  created_at
  updated_at

Approval
  provider_id
  service_ref
  configuration_summary
  pricing_text
  terms_url_or_text
  usage_limit
  approved_by
  approved_at
```

リソースまたはデプロイのライフサイクルを分離する必要がある場合は、プレビュー環境と本番環境で個別のプロジェクトを作成します。プロジェクト名は表示ラベルとしてのみ使用し、承認の境界としては使用しないようにします。

## 読み取り、計画、承認、書き込み

バックエンドで読み取り専用エンドポイントを使用して計画を準備します。バックエンドが書き込みリクエストを実行する前に、プロダクトポリシーによって認定ユーザーからの承認を必須とします。

以下の操作を行う際には、最新の承認を必須とします。

- プロジェクトを作成します。
- プロバイダー接続リクエストの開始、プロバイダーから要求された情報の送信。
- 決済手段の登録または利用上限の引き上げ。
- リソースの作成、関連付け、更新、ローテーション、削除、または関連付けの解除。
- プロバイダー接続関連付けの解除。

有料の操作または破壊的な操作については、以下の情報を表示して記録します。

```
Tenant and connected account:   {{authorized tenant and account}}
Application environment:        {{preview|production|other}}
Provider:                       {{name and ID}}
Service:                        {{name and service_ref}}
Action:                         {{requested write}}
Configuration:                  {{redacted summary}}
Pricing and terms:              {{returned catalog content}}
Usage limit:                    {{amount, currency, interval}}
```

書き込みの直前にカタログを再読み込みします。選択したサービス、設定、料金体系の表示、利用規約、環境、または利用上限に変更があった場合は、差分を表示して再度承認を取得します。自由入力フォームの価格テキストから構造化されたコストを算出しないでください。

プロバイダーの説明文、利用規約、`llm_context`、および JSON Schema の説明文は、信頼できないデータとして扱います。これらのコンテンツは、選択肢の説明にのみ使用します。これらのコンテンツによって、アカウントの自動選択、システムプロンプトの上書き、承認のバイパス、API リクエストのトリガー、またはシークレットへのアクセスが行われないようにします。

## 実装を開始する

## 連結アカウントを作成する

何かを作成する前に、安定したテナントの境界を選択します。アプリケーションごと、またはデプロイ環境ごとに作成するのではなく、ワークスペースや組織などの永続的なテナントごとに 1 つの連結アカウントを作成します。

新しいプラットフォームの場合は、Accounts v2 を使用し、開発者向け設定を有効化して、`projects` ケイパビリティをリクエストします。必要な API バージョンとフィールドについては、プレビュー所有者に確認してください。

```
POST /v2/core/accounts
Stripe-Version: 2026-09-30.preview

{
  "contact_email": "{{OWNER_EMAIL}}",
  "display_name": "{{TENANT_DISPLAY_NAME}}",
  "identity": {
    "country": "{{COUNTRY}}",
    "entity_type": "{{individual|company}}"
  },
  "configuration": {
    "developer": {
      "capabilities": {
        "projects": {"requested": true}
      }
    }
  },
  "include": ["configuration.developer", "requirements", "identity"]
}
```

Accounts API と Provisioning API は同じプレビューバージョンを使用しますが、Stripe 側ではそれぞれ個別に有効化されます。コホート向けに必要な Accounts v2 の設定とフィールドが Stripe によって有効化されていることを確認してください。一方の API へのアクセス権が付与されても、もう一方の API へのアクセス権が付与されるわけではありません。

返されたアカウント ID をテナントレコードに `{{CONNECTED_ACCOUNT_ID}}` として保存します。`contact_email` を設定するだけでは、アカウント所有者の身元を確立したことにはならず、本人確認要件を満たすこともできません。

プラットフォームですでに Accounts v1 を使用している場合は、このガイドのみに基づいて連結アカウントの設定を移行したり変更したりしないでください。サポートされているプレビューのアカウント登録手順について、プレビュー所有者に確認します。

## ホスト型アカウント登録にユーザーを誘導する

Create an Account Link for account onboarding, then redirect the authenticated user to its short-lived URL:

```
POST /v2/core/account_links
Stripe-Version: 2026-09-30.preview

{
  "account": "{{CONNECTED_ACCOUNT_ID}}",
  "use_case": {
    "type": "account_onboarding",
    "account_onboarding": {
      "refresh_url": "{{PLATFORM_REFRESH_URL}}",
      "return_url": "{{PLATFORM_RETURN_URL}}",
      "collection_options": {"fields": "currently_due"}
    }
  }
}
```

URL の期限が切れた場合は、別のリンクを作成します。その後の修正には、`account_update` を使用します。

```
POST /v2/core/account_links
Stripe-Version: 2026-09-30.preview

{
  "account": "{{CONNECTED_ACCOUNT_ID}}",
  "use_case": {
    "type": "account_update",
    "account_update": {
      "refresh_url": "{{PLATFORM_REFRESH_URL}}",
      "return_url": "{{PLATFORM_RETURN_URL}}"
    }
  }
}
```

`refresh_url` と `return_url` の両方のハンドラーで認証します。refresh ハンドラーは、同じ目的を持つ新しいアカウントリンクを作成します。

ユーザーが戻ってきたら、アカウントを取得します。

```
GET /v2/core/accounts/{{CONNECTED_ACCOUNT_ID}}?include=configuration.developer&include=requirements
Stripe-Version: 2026-09-30.preview
```

DeveloperConfig の Projects ケイパビリティと、未対応の要件を確認します。アカウントリンクからのリダイレクトのみを、完了の証明として扱わないでください。

`projects` ケイパビリティがアクティブになり、必要なアカウント登録が解決された後にのみ、プロビジョニングを開始します。コホートでケイパビリティステータスのイベントが有効化されている場合、そのイベントは信頼できる情報源としてではなく、アカウント情報を取得するためのプロンプトとして扱います。

## 連結アカウントの利用資格を確認する

```
GET /v2/provisioning/eligibility
```

利用資格はカタログの利用可否とは切り離して解釈します。

| 結果 | プラットフォームのアクション |
| --- | --- |
| `is_eligible=false` | 中断します。テナントとアカウントの関係、および現在のコホート登録状況を確認した上で、承認済みアカウント登録の修復手順に従います。 |
| `requirements` 配列が空ではない `is_eligible=true` | アカウントの準備が完全に完了したとはみなさないでください。必要な本人確認や利用規約への同意手続きを承認済みのアカウント登録手順で誘導し、その後に現在の状態を再度取得します。 |
| requirements が存在しない `is_eligible=true` | カタログ、請求、接続、および承認の確認に進みます。 |

アカウントの利用資格、アカウント登録の要件、サービスの利用可否、および独自のプロダクトポリシーは、それぞれ独立した 4 つのゲートです。利用資格のレスポンスが `true` であっても、利用できないサービスが使用可能になるわけではなく、有料の書き込みが承認されるわけでもありません。

## プロビジョニング可能なサービスを検出する

計画時とプロビジョニングの直前に、連結アカウントのカタログを再度読み取ります。

```
GET /v2/provisioning/catalog/providers?limit=100
GET /v2/provisioning/catalog/services?provider_name={{PROVIDER_NAME}}&limit=100
```

上記のどちらの呼び出しでも、制限付きキーには `rak_provisioning_project_read` が必要です。

#### サービスを選択する

候補となるプロバイダーごとに、そのプロバイダーの正確な `provider_name` と、同じカタログおよび開発用の選択項目を使用してサービスを一覧表示します。サービスのレスポンスに含まれる `data` 配列が空の場合、そのプロバイダーはこのプランではプロビジョニングできません。そのプロバイダーに対してプロバイダー接続リクエストを作成しないでください。

API には一般的な全文検索やカテゴリー検索用のパラメーターは用意されていません。これらを作成しないでください。すべてのページを最後まで辿り、返された `data` からローカルインデックスを構築した上で、決定論的なプロダクトポリシーを適用してください。その後、モデルによる説明やランキングの提示には、返された対象サービスのみを渡すようにします。

| カタログフィールド | 用途 |
| --- | --- |
| Provider `id` | `provider` という名前のリクエストフィールドで送信します。 |
| Provider `name` | ユーザーに表示し、`provider_name` を明示的に受け付けるエンドポイントにのみ送信します。 |
| Provider `configuration_schema` | プロバイダー接続リクエストを作成する前に、接続設定を検証します。 |
| Service `service_id` | リソースの作成、関連付け、または更新時にこの値を `service_ref` として送信します。 |
| Service `configuration_schema` | リソースの作成または更新時にこのスキーマを使用して設定を検証します。 |
| `availability` | 利用不可のサービスを除外します。 |
| `pricing.paid_pricing` | 有料プランの料金表示にはこのフィールドを使用します。非推奨の `pricing.paid` フィールドは使用しないでください。 |
| `kind` と component の `parent_services` | プラン、デプロイ可能リソース、コンポーネント、および前提条件となるサービスを特定します。 |
| `scope` | プロジェクトの配置と関連付けを決定します。 |
| `constraints`、`allowed_updates` | サポートされていない作成と変更を防ぎます。 |
| Provider `capabilities` | プロバイダー側が公開している場合にのみ、オプションの動作を有効化します。 |

カタログリクエスト、およびそれをサポートするすべてのプロジェクトまたはリソースのリクエストには、同一のカタログパーティションを使用します。ユーザーが開発環境専用のエントリーを選択した場合にのみ、`development=true` を設定します。

#### 接続またはプロビジョニングの前に依存関係を計画する

プロバイダーは、プランのサービスとそれに依存するデプロイ可能リソースのサービス、または `parent_services` を持つコンポーネントサービスを公開できます。必須のプランと親サービスを、プラン内の個別リソースとして扱います。

```
Plan prerequisite
  → user approves prerequisite and dependent action
  → create prerequisite Resource
  → wait for complete
  → refresh catalog and approval-sensitive fields
  → create dependent Resource
```

依存関係の情報が不明確な場合は、さまざまなプロバイダーやサービスをテストするのではなく、処理を中断してください。プロバイダーから返される生の HTTP ステータスコードをクライアント向けの仕様の一部として扱わないでください。代わりに、Provisioning API の状態、エラーコード、および安全なエラーメッセージを使用します。

## 有料サービス向けの請求を設定する

まず、有効な連結アカウントのプロファイルを取得します。

```
GET /v2/provisioning/payment_profile?livemode=false
```

すべての読み取りでクエリパラメーターとして `livemode` を設定します。この値では決済手段が作成されたモードは継承されず、エンドポイントは `Stripe-Livemode` ヘッダーを無視します。テスト環境のプロファイルを読み取るには `livemode=false` を送信します。クエリパラメーターを省略したりヘッダーのみで設定したりすると、テストモードのプロファイルが存在していても `404` が返されるため、書き込みが成功していても警告なしに失敗したかのように見えてしまいます。

「決済手段がまだ関連付けられていません」というメッセージを伴う `404 not_found` は、アカウントにとって正常な初期状態であり、エラーではありません。これを「決済手段がまだない」状態として扱い、いずれかの決済パスに進みます。

コホート向けに明示的に有効化されているいずれかの決済パスを使用します。

| パス | リクエスト |
| --- | --- |
| 連結アカウントのホスト型収集 | `usage_limits` を指定して決済手段のリクエストを作成します。`payment_method_owner` およびすべての `source_*` フィールドは省略します。認定ユーザーを、返された有効期間の短い `checkout_session_url` に誘導し、一致する `livemode` クエリパラメーターを使用して決済プロファイルをポーリングします。 |
| プラットフォーム所有のソース | Stripe がプレビューコホート向けに明示的にこのフローを有効にしている場合にのみ使用します。書き込みリクエストを送信する前に、Customer と PaymentMethod が同一のソースアカウントに属していることを確認します。リクエストには、`payment_method_owner: "platform"`、`source_account`、`source_customer`、`source_payment_method`、および `usage_limits` を含めてください。 |

連結アカウントのホスト型収集では、`usage_limits` のみを送信します。

```
POST /v2/provisioning/payment_method_requests

{
  "livemode": false,
  "usage_limits": {
    "max_amount": "5000",
    "currency": "usd",
    "recurring_interval": "month"
  }
}
```

レスポンスとして `checkout_session_url` と `status` が返されます。

プラットフォーム所有のソースパスでは、同じエンドポイントに対して所有者とソースのフィールドを送信します。

```
POST /v2/provisioning/payment_method_requests

{
  "livemode": false,
  "payment_method_owner": "platform",
  "source_account": "{{PLATFORM_ACCOUNT_ID}}",
  "source_customer": "{{PLATFORM_CUSTOMER_ID}}",
  "source_payment_method": "{{PAYMENT_METHOD_ID}}",
  "usage_limits": {
    "max_amount": "5000",
    "currency": "usd",
    "recurring_interval": "month"
  }
}
```

`max_amount` は通貨の最小単位を使用し、文字列として送信します。API は int64 のフィールドを文字列として表すため、引用符で囲まれていない数値は `invalid_fields` でエラーになります。すべての大きな数値を扱うフィールドに対して、同じ規則を適用します。有効な期間は `week`、`month`、および `year` です。アカウント全体の上限やプロバイダー固有の上書きを設定するには、同様に金額を文字列として受け取る `POST /v2/provisioning/payment_profile/update_limit` を使用します。

決済モード、カタログパーティション、およびアプリケーション環境はそれぞれ独立した設定として扱ってください。`dev` や `testing` カタログにアクセスできても、プロバイダーがインフラストラクチャを作成しない、または決済を承認しないという保証にはなりません。プレビュー環境へのデプロイであっても決済モードが変更されることはありません。登録済みコホートとプロバイダーが別段の取り決めを明示的に確認していない限り、有料の検証は課金が発生する可能性があるものとして扱ってください。

決済設定の完了は、プロバイダー接続、有料リソース、プラン階層の変更、または利用上限額の引き上げが承認されるわけではありません。各アクションに対して、個別にユーザーの承認を必須とします。

Provisioning の利用上限は、ライフサイクルポリシーではなく、承認の上限として扱ってください。上限に達したからといって、リソースが自動削除される、サービスの提供状況が維持される、またはすべてのプロバイダーで同一の通知がトリガーされると想定しないようにします。サービスおよびプロバイダーの仕様を確認し、上限をユーザーから確認できる状態に保ち、ユーザーが承認した上で上限を変更できる手段を提供します。

#### 既存のプラットフォームの顧客を Provisioning テナントにマッピングする

ユーザーがすでにプラットフォーム上に `Customer` オブジェクトおよび保存済みの決済手段を保持している場合でも、それらを移行したり置き換えたりする必要はありません。1 人のユーザーがプラットフォームの Customer であると当時に連結アカウントでもあるという構成が可能です。

```
Platform user
├── Platform Customer: stores the payment method for your platform's own charges
└── Connected account: owns Provisioning Projects, Provider connections,
    Resources, usage, and the payment profile
```

- プラットフォームの Customer ではなく、Provisioning の決済プロファイルがプロバイダーのサービスを承認します。
- プラットフォーム所有のソースパスを使用すると、すでに保存済みの決済手段に対して請求できますが、これが利用できるのはコホート向けに明示的に有効化されている場合に限られます。
- Provisioning API は、プラットフォームをプロバイダーサービスのマーチャントオブレコードにするものではなく、Connect の送金やマーケットプレイスモデルを実装するものでもありません。これらが必要な場合は、Connect を使用して個別に設計してください。

## プロジェクトを作成する

承認後、アプリケーション環境用のプロジェクトを作成します。

```
POST /v2/provisioning/projects

{
  "name": "{{APPLICATION_NAME}} {{ENVIRONMENT}}"
}
```

プロジェクト ID をプラットフォーム側のアプリケーション環境レコードに保存してます。リソースや認証情報を分離して保持する必要がある場合は、プレビュー用と本番環境用で別々のプロジェクトを使用してください。

## プロバイダーを接続する

新しいリクエストを作成する前にプロバイダー接続を一覧表示します。

```
GET /v2/provisioning/provider_connections?limit=100
```

複数の有効な接続が存在することで結果が曖昧になる場合は、取得可能な範囲で安全なプロバイダーアカウントの返却詳細情報を表示し、確認のために処理を中断します。使用可能な有効な接続が存在しない場合は、プロバイダーの `configuration_schema` を検証した上で、承認後にプロバイダー接続リクエストを作成します。

```
POST /v2/provisioning/provider_connection_requests

{
  "provider": "{{PROVIDER_ID}}",
  "configuration": {},
  "project": "{{PROJECT_ID}}"
}
```

プロバイダーのスキーマに必須フィールドが存在しない場合にのみ、`{}` を使用します。ユーザーをリダイレクトしたり追加情報を収集したりする前に、返されたプロバイダー接続リクエスト ID を保存します。

リソースをプロビジョニングする前に、プロバイダーの有効な接続が 1 つだけ存在することを確認します。リソースの作成および関連付けリクエストはプロバイダーを特定するものであり、特定のプロバイダー接続を指定するものではありません。書き込み API は選択された接続を使用できないため、接続の選択画面を表示しないでください。

| プロバイダー接続リクエストのステータス | プラットフォームのアクション |
| --- | --- |
| `requested` | 次のステータスに進むか、あらかじめ設定した期限が切れるまで、プロバイダー接続リクエストを取得し続けます。 |
| `pending_auth` | 認証済みのユーザーにのみ `redirect_url` を提示して状態を永続化し、バックエンドからポーリングを行います。 |
| `needs_information` | サポートされている `needs_information_schema` の構造に応じてレンダリングし、ユーザーが入力した値のみを収集して、`{ "information": {{VALIDATED_INFORMATION}} }` を送信します。プロバイダーのフローから返された場合にのみ `confirmation_secret` を含め、シークレットとして扱ってください。 |
| `complete` | 生成された接続を `provider_connection` から読み取り、有効な接続が明確であることを確認します。リクエストは、該当する接続の関連付けが解除された後も `complete` のままになりますが、その場合 `provider_connection` は存在しません。 |
| `error` | 中断し、安全なエラーのみを表示します。 |

作成レスポンスそのものにおいて、即時接続パスを処理します。一部のプロバイダーは作成リクエストの処理中に完了し、有効な `provider_connection` を伴い、`redirect_url` なしで `complete` を返します。そのため、リダイレクトを待機したり、すでに完了したリクエストに対してポーリングを継続したりしないでください。

プロダクトでは任意項目として扱われている情報であっても、プロバイダー側が確認済みのメールアドレスなど、KYC 情報を必須とする場合があります。プロバイダーの `configuration_schema` および返された `needs_information_schema` で必須フィールドを特定してください。メールアドレスが指定されている場合を含め、要求されているすべての必須情報を収集して送信します。

プロバイダーの認証にブラウザーのリダイレクトが必要な場合は、ワークフローを一時停止し、プロバイダー接続リクエスト ID を保存します。ブラウザーでの手続きが完了した後、その ID を使用してワークフローを再開します。認証をバイパスしたりシミュレートしたりしないでください。

現在のフローでは、プラットフォーム側のコールバック URL は受け付けられません。Stripe でプロバイダーのコールバックおよびトークン交換が処理されます。任意の PKCE フィールドは Stripe がフィールドフロー向けに明示的に有効化し、要求している場合にのみ指定します。

## リソースを作成または関連付ける

書き込みリクエストを送信する前に、以下を確認します。

- 必須のアカウント登録が完了していること。
- 選択されたカタログ内で対象のサービスが引き続き利用可能であること。
- 前提条件となるプランまたは親リソースがすべて完了していること。
- プロバイダーに有効な接続が 1 件のみ存在すること。
- リソースの設定が現在のサービスの `configuration_schema` を満たしていること。
- 各有料サービスに対して決済プロファイルが存在すること。
- リソースの `scope`、`constraints`、許可された更新、プロジェクトとの関連付けが有効であること。
- ユーザーが現在のプランを承認していること。

```
POST /v2/provisioning/resources

{
  "provider": "{{PROVIDER_ID}}",
  "service_ref": "{{SERVICE_ID}}",
  "project": "{{PROJECT_ID}}",
  "livemode": {{true|false}},
  "name": "{{RESOURCE_NAME}}",
  "configuration": {{VALIDATED_SERVICE_CONFIGURATION}}
}
```

作成リクエストおよび関連付けリクエストでは、常に `livemode` を明示的に設定します。省略した場合、Stripe のデフォルトは `true` となり、本番環境のプロバイダーインフラストラクチャが作成され、実際の請求が発生する可能性があります。テスト環境でのプロビジョニングには、`livemode` を `false` に設定します。

リソースの `environment` フィールドが受け付ける値は、`dev` または `prod` のみです。プレビューや本番などのアプリケーション環境をこれらの値のいずれかにマッピングします。`environment` フィールドと `livemode` フィールドは互いに独立しています。`environment=dev` が設定されていても、リソースがサンドボックス内で実行されることを意味するわけではありません。

プロジェクトスコープのサービスの場合は、`project` を含めます。アカウントスコープのサービスの場合は、リソースをプロジェクトに関連付ける必要がない限り `project` を省略します。`project` を含めると関連付けは作成されますが、プロバイダー側のリソースのスコープが変更されるわけではありません。

既存のインフラストラクチャを取り込むのは、プロバイダーが `resources:link` を公開しており、かつユーザーがそれを承認した場合にのみ行ってください。

```
POST /v2/provisioning/resources/link

{
  "provider": "{{PROVIDER_ID}}",
  "service_ref": "{{SERVICE_ID}}",
  "project": "{{PROJECT_ID}}",
  "environment": "{{dev|prod}}",
  "catalog": "{{CATALOG}}",
  "livemode": {{true|false}}
}
```

## 非同期処理を安全に再開する

リソースが使用可能になるのは、`status=complete` の場合のみです。

| リソースのステータス | プラットフォームのアクション |
| --- | --- |
| `pending` | 制限付きの指数バックオフとジッターを使用して `GET /v2/provisioning/resources/{id}` をポーリングします。 |
| `needs_information` | スキーマに準拠したユーザー入力を収集し、`{ "submitted_information": {{VALIDATED_INFORMATION}} }` を送信した上でポーリングを続行します。 |
| `complete` | そのリソースをアプリケーション環境に対応付けて記録し、ワークフローを続行します。 |
| `errored` | 中断し、安全である場合にのみ `error_message` を公開します。 |
| `removed` | 最終状態として扱います。 |

プレビュー期間中は、1 秒、2 秒、4 秒、8 秒、16 秒、30 秒の間隔でポーリングし、その後は最長 15 分間にわたり 30 秒ごとにポーリングします。同時に開始されたワークフローが同じタイミングでポーリングを送信しないよう、各待機時間にジッターと呼ばれる小さなランダムのオフセットを追加します。この API では、ポーリング間隔、Webhook、または最終的なレート制限は定義されません。ポーリングがタイムアウトした場合は、オブジェクト ID を保持したまま、ステータスを `requires_review` に設定してください。書き込みリクエストを自動で再送信しないでください。

## Retrieve Resource credentials

After the Resource reaches `status=complete`, retrieve its current Provider-issued access configuration from your backend:

```
POST /v2/provisioning/resources/{id}/reveal_access_configuration
```

Don’t send a request body. For a restricted key, grant the `provisioning_resource_reveal_access_configuration` permission.

The endpoint returns the latest available access configuration:

```json
{
  "object": "v2.provisioning.resource_access_configuration",
  "created": "2026-09-21T14:00:00Z",
  "resource": "fres_123",
  "livemode": false,
  "configuration": {
    "DATABASE_URL": "postgres://USER:PASSWORD@db.example.test/DATABASE"
  },
  "expires_at": "2026-09-22T14:00:00Z"
}
```

Treat the complete response as a secret. Copy only the required configuration values into your deployment system’s secret store. Don’t return the response to a browser or include configuration names or values in logs, analytics, support tickets, or model prompts. The optional `expires_at` field is absent when the Provider doesn’t define an expiration time.

Retrieving an access configuration doesn’t rotate credentials and doesn’t require an idempotency key. To obtain replacement credentials, rotate the Resource first. If the rotation returns `complete`, retrieve the new access configuration.

Send the same verified `Stripe-Context` value that you used to create or retrieve the Resource. Only retrieve credentials for a Resource that your authenticated user is authorized to access.

## リソースを管理する

### 更新する

更新の前に、サービスをリフレッシュし、`allowed_updates`、`constraints`、現在のカタログ、および承認状況を確認します。

```
POST /v2/provisioning/resources/{id}

{
  "configuration": {{VALIDATED_SERVICE_CONFIGURATION}},
  "service_ref": "{{OPTIONAL_NEW_SERVICE_ID}}",
  "catalog": "{{CATALOG}}"
}
```

設定のみの更新の場合は `service_ref` を省略します。レスポンスは操作結果 (`pending`、`complete`、または `errored`) となります。レスポンスに含まれる非推奨の `resource_id` には依存しないでください。

### 認証情報をローテーションする

`POST /v2/provisioning/resources/{id}/rotate_credentials` は、`pending`、`complete`、または `errored` を返します。

- `complete`: リソースに対するローテーションを記録し、ローテーション前にプロバイダーによって発行された認証情報を無効化します。
- `errored`: ワークフローを中断し、リソースを変更前の状態で維持します。
- `pending`: ローテーションリクエストを再送信しないでください。ステータスを `requires_review` に設定します。プレビュー API ではローテーション操作を取得する永続的な手段が用意されておらず、後からリソースを読み取ってもローテーションが完了したことは確認できません。

### 削除、関連付け解除、および接続の関連付け解除を行う

アクションごとに個別の承認を要求します。

| アクション | エンドポイント | 効果 |
| --- | --- | --- |
| インフラストラクチャのプロビジョニングを解除する | `POST /v2/provisioning/resources/{id}/remove` | プロバイダーのインフラストラクチャの削除をリクエストします。 |
| リソースの管理を中断する | `POST /v2/provisioning/resources/{id}/unlink` | プロビジョニングの関連付けを削除します。プロバイダーのインフラストラクチャは削除されません。 |
| プロバイダー接続を消去する | `POST /v2/provisioning/provider_connections/{id}/unlink` | Stripe に保存されている接続情報を削除します。リソース側は削除されず、プロバイダー側でのトークン失効も保証されません。 |

リソースの削除または関連付け解除後に、プロバイダーが以前発行された認証情報をすでに無効化していると仮定しないでください。プロバイダー側でそれらのステータスを確認します。

## エラーの処理

エラー処理には、Provisioning API の `error.code`、返された状態、および安全なメッセージを使用します。プロバイダー固有の生の HTTP ステータスを推測して条件分岐を行わないでください。

| エラーコード | プラットフォームのアクション |
| --- | --- |
| `payment_method_required` | 決済の設定を完了し、承認を取得した上で、慎重に再試行します。 |
| `payment_method_and_customer_required` | 有効化されたプラットフォームソースフローの場合、一致するソース側の Customer と PaymentMethod を指定します。 |
| `payment_method_owner_required` | 有効化されたプラットフォームソースフローの場合、`payment_method_owner=platform` を設定します。 |
| `unsupported_payment_method_owner` | 中断し、現在有効化されている所有者モードのみを使用します。 |
| `connect_relationship_required` | プラットフォームと連結アカウントの関係および `Stripe-Context` の値を確認します。 |
| `provider_reauth_required` | 新しいプロバイダーの接続リクエストを作成し、ユーザーに再接続を依頼します。 |
| `invalid_resource_configuration` | スキーマを更新し、修正されたユーザー入力を収集します。 |
| `resource_count_constraint_exceeded` | 制約事項を説明し、許可された更新、関連付け、または既存のリソースを提示します。 |
| `resource_not_complete` | Retrieve the Resource and follow its current status. Poll only while it is `pending`, submit required information when it is `needs_information`, and stop if it is `errored` or `removed`. Retrieve the access configuration after the Resource reaches `complete`. |
| `resource_access_configuration_unavailable` | Stop. Relink or rotate the Resource, or follow the Provider guidance in its status details. |
| `resource_access_configuration_expired` | Rotate the Resource credentials. If the rotation returns `complete`, retrieve the replacement. If it returns `pending`, set the workflow status to `requires_review`. |
| Missing-permission HTTP `403` | Use a key with the `provisioning_resource_reveal_access_configuration` permission. |
| Other HTTP `403` | Verify private-preview enrollment, the `Stripe-Context` account, and the Resource’s Project scope. Don’t add permissions unless the error identifies a missing permission. |
| `provider_failure` | 安全なメッセージを表示します。可能な場合はレスポンスとして返された前提条件を特定し、承認を得た上で安全である場合にのみ再試行します。 |
| `api_error` または不明なコード | 処理を中断し、安全な診断情報を記録して、既知のオブジェクトを取得し、`requires_review` としてマークします。書き込みは自動で再実行しないでください。 |
| `not_found` | オブジェクト ID と `Stripe-Context` を確認します。別のアカウントへのプローブは行わないでください。 |
| `rate_limited` または HTTP `429` | レスポンスに `Retry-After` が含まれている場合はそれに従い、指数バックオフとジッターを使用して待機します。ポーリング間隔を短縮したり、複数のリソースにわたって再試行を拡散させたり、並行呼び出し元を追加して制限を回避しようとしたりしないでください。 |

`api_error`、利用不可のリクエストログ、または不明な書き込み結果については、エンドポイント、アクション、シークレットを含まないリクエスト ID、オブジェクト ID、HTTP ステータス、エラーコードとメッセージ、現在のワークフローの状態を保存します。`request_log_url` が存在しない、利用できない、または役に立たない場合は、その結果を証拠として記録します。ユーザーに対してその URL の再試行を繰り返し求めないでください。

書き込みリクエストがタイムアウトしたか、不明な結果が返された後は、ワークフローのステータスを `requires_review` に設定します。同じ連結アカウントのコンテキスト内で、既知のプロバイダー接続リクエストとリソースを取得します。確認された状態を認定ユーザーと照合し、別の書き込みリクエストを送信する前にそのユーザーからの承認を取得します。元のリクエストを自動で再実行しないでください。

## 実装のテスト

デプロイ前に、コホートで明示的に登録したアカウントとサービスを用いてテストします。

1. ユーザーからテナント、連結アカウントに至るまでの承認を確認します。信頼されていないアカウント ID ではコンテキストは変更できないことを確認します。
2. 連結アカウントのアカウント登録を完了し、要件が空の場合と空でない場合の両方でアカウントの準備ができていることを確認します。
3. ページネーション、カタログと開発パーティションの整合性、空のサービスリスト、提供状況、価格設定、スコープ、制約事項、およびスキーマの検証をテストします。
4. プロバイダー固有の生の `422` レスポンスを分岐することなく、プランの依存関係、デプロイ可能な依存関係、およびコンポーネントと親の依存関係をテストします。
5. 即時プロバイダー接続、ブラウザーのリダイレクト、および `needs_information` をテストします。ブラウザーやセッション切断が発生した後のワークフロー復旧を確認します。
6. 無料リソースを用いて、`pending`、`needs_information`、および完了に至る流れをテストします。
7. 有料のプロビジョニングのテストは、コホートによる確認が得られた場合にのみ実施し、明示的な低い上限額を設定した上で、新しく承認を取得します。
8. 更新、再認証、およびリソースの削除と関連付け解除を個別にテストします。
9. Test credential retrieval for authorized Resources. Verify that incomplete, unavailable, expired, cross-account, and cross-Project Resources don’t disclose credentials.
10. Test synchronous credential rotation, verify that retrieval returns the committed replacement only after rotation completes, and require review for pending rotation.
11. `provider_failure`、`api_error`、ポーリングのタイムアウト、不明な書き込み、および利用できないリクエストログのリンクについてテストします。

## プレビューの制限事項

- Access configurations are retrieved one Resource at a time. The preview doesn’t provide bulk credential retrieval.
- ドキュメントに記載されたプロビジョニングの Webhook サポートは存在しないため、制限付きポーリングを使用します。
- 書き込みに関する呼び出し側の冪等性や関連付けの仕様は記載されていません。
- クライアントのポーリング間隔や最終的なレート制限ポリシーに関する記載はありません。一部のプロバイダーは厳格なレート制限を設けており、多数のリソースやプロジェクトにリクエストを拡散させる呼び出し元は、ユーザーあたりのリクエスト数が中程度であってもこの制限に達する可能性があるため、ワークフローごとではなく中央で集約して待機します。
- プロバイダーのアップストリームでの障害は安定したクライアントインターフェイスではないため、Provisioning API のコードと安全なメッセージを使用します。
- 保留中の認証情報のローテーションには、永続的な操作の取得フローがありません。
- 有料のテストプロビジョニングおよびプラットフォーム所有の決済ソースはコホートに依存します。
- プレビューのフィールドと列挙型は変更される可能性があるため、代替となる現在のフィールドが存在する場合は非推奨のフィールドを避けてください。

## See also

- [Stripe Projects CLI](https://docs.stripe.com/projects.md)
- [利用可能なプロバイダー](https://docs.stripe.com/projects.md#available-providers)
- [Stripe Projects のプロバイダー登録](https://docs.stripe.com/projects/provider-intake.md)
- [Stripe Connect](https://docs.stripe.com/connect.md)
- [Accounts v2](https://docs.stripe.com/connect/accounts-v2.md)