# 制限付き API キー

制限付き API キーを使用して、アプリケーションの Stripe API へのアクセスを制御できます。

制限付き API キー (RAK) を使用して、特定の Stripe API 権限を API キーに割り当てることができます。このような RAK を使用すると、API キーが悪意のある第三者にさらされた場合に、ビジネスへの潜在的な損害を抑えられます。制限付き API キーに API リクエストを完了するための適切な権限がない場合、Stripe は[無効なリクエストエラー](https://docs.stripe.com/error-handling.md#invalid-request-errors)を返します。

## 制限付き API キーとは

Stripe に登録すると、[シークレット API キー](https://docs.stripe.com/keys.md#obtain-api-keys) (`sk_live_` または `sk_test_` で始まる) が発行されます。シークレットキーを持つ個人、エージェント、またはシステムは、Stripe アカウントで *あらゆる* 操作を実行できます。たとえば、請求の作成、返金の実行、顧客データの読み取り、入金の実行などです。

制限付き API キー (RAK) は `rk_live_` または `rk_test_` で始まり、実行できる操作を必要なものだけに制限できます。Dashboard で RAK を作成する際は、そのキーがアクセスできる Stripe リソースと、各リソースに対する権限 (**Read**、**Write**、**None**) を選択します。すべての Stripe API は制限付き API キーに対応しています。

キーが漏洩または侵害された場合に Stripe アカウントを保護するための防御策として、制限付きキーを使用できます。悪意のある第三者が制限付き API キーを入手しても、そのキーに設定された権限の範囲でしか操作できません。たとえば、不審請求の申し立てデータだけを読み取れる制限付きキーを作成できます。悪意のある第三者がそのキーを入手しても、不審請求の申し立てデータを読み取ることしかできません。請求の作成、顧客の決済手段へのアクセス、入金の実行はできません。

Stripe では、制限のないシークレットキーではなく、常に制限付きキーを使用することを推奨しています。制限付きキーを使用する場合は、偶発的な漏洩や侵害を防ぐため、常にベストプラクティスに従ってください。詳しくは、[シークレット API キーを管理するためのベストプラクティス](https://docs.stripe.com/keys-best-practices.md)をご覧ください。

## シークレットキーではなく制限付きキーを使用する理由

|                   | シークレットキー (`sk_`)             | 制限付きキー (`rk_`)                    |
| ----------------- | ---------------------------- | --------------------------------- |
| **アクセスの範囲**       | すべての API リソースへのフルアクセス        | 割り当てる権限のみ                         |
| **侵害された場合の影響**    | 悪意のある第三者はアカウントであらゆる操作を実行できます | 悪意のある第三者が実行できるのは、そのキーで許可された操作のみです |
| **サードパーティーによる共有** | 危険: サードパーティーに完全な制御権を与えます     | より安全: サードパーティーに必要なアクセスのみを提供します    |
| **最小特権の原則**       | 制限のないキーでは実現できません             | キーに最小限の権限を付与できます                  |
| **Stripe の推奨事項**  | 使用は最小限にとどめ、厳重に保護します          | **推奨**: 可能な限り制限付きキーを使用します         |

### 制限付き API キーに切り替える理由

- **潜在的なキーの乗っ取りによる影響を制限する**: 制限付きキーが侵害された場合でも、悪意のある第三者がアクセスできるのは、そのキーに対して許可した特定のリソースだけです。

- **第三者とキーを安全に共有する**: Stripe はほとんどの場合、キーの共有を推奨していませんが、特定のサードパーティー連携ではキーの共有が必要になることがあります。たとえば、ベンダーが不審請求の申し立てを監視する必要がある場合は、制限のないシークレットキーではなく、不審請求の申し立てへの読み取り専用アクセス権を持つ制限付きキーを付与します。サードパーティーと連携している場合は、可能であれば IP 許可リストを使用してキーが侵害されるリスクを軽減し、関係が終了したらキーを失効させるなど、キーを安全に扱うための[ベストプラクティス](https://docs.stripe.com/keys-best-practices.md)に必ず従ってください。

- **コンプライアンス要件に対応**: 多くのセキュリティ監査やコンプライアンスフレームワークでは、最小権限の原則に従うことが求められます。制限付きキーを使用すると、その対応を簡単に行えます。

- **IP 制限と組み合わせる**: 制限付きキーを特定の IP アドレス群に限定して、追加の防御層として利用できます。

## シークレットキーから制限付きキーに移行する

制限付き API キーは、シークレット API キーの置き換えとしてそのまま使用できます。制限付き API キーを使用するには、キーが誤って公開されないよう、[ベストプラクティス](https://docs.stripe.com/keys-best-practices.md)に従って、シークレットキーと同じ方法でコードに設定してください。すべての Stripe API が制限付き API キーに対応しています。制限付きキーのメリットを得るには、各キーの権限を設定する必要があります。

ここでは、シークレットキーから制限付きキーに移行するための手順を追って説明します。制限付き API キーの権限を減らす方法については、[制限付き API キーに権限を割り当てる](https://docs.stripe.com/keys/restricted-api-keys.md#assign-permissions)をご覧ください。

### シークレットキーの API 使用状況を確認する

コードとサードパーティー連携を確認し、使用している Stripe 製品と、現在シークレットキーで実行している API コールリクエストを整理します。

シークレットキーの[ワークベンチのリクエストログ](https://dashboard.stripe.com/workbench/logs)を確認します。以下の表を使用して、成功した API リクエストを必要な RAK 権限に対応付けることができます。

| HTTP メソッド | RAK 権限の種類 |
| --------- | --------- |
| GET       | 読み取り      |
| POST      | 書き込み      |
| DELETE    | 書き込み      |

たとえば、`GET /v1/customers` へのコールが成功した場合は、[顧客](https://docs.stripe.com/api/customers.md)リソースの読み取り権限を代替 RAK の権限に追加する必要があります。

### サンドボックスで制限付きキーを作成する

Stripe では、本番環境のキーを作成する前に、Stripe サンドボックスで制限付きキーを作成することを推奨しています。

1. Stripe Dashboard の [API キーページ](https://dashboard.stripe.com/apikeys)に移動します。
1. **制限付きキーを作成** をクリックします。
1. `billing-service-test` のようなわかりやすい名前を付けます。
1. 各リソースについて、先ほど確認した API の使用状況に基づき、権限を **None**、**Read**、または **Write** に設定します。

### 制限付きキーを使用するようにステージング環境を構成する

テストアプリケーションまたはステージングアプリケーションで、サーバー環境 (環境変数やシークレットボールトなど) のシークレットキーを制限付きキーに置き換えます。キーを使用する Stripe SDK と HTTP コールは、これまでどおり同じように動作します。異なるのはキーの値だけです。

### 制限付きキーのリクエストログでエラーを確認し、権限を調整する

制限付きキーの横にあるオーバーフローメニュー (⋯) をクリックし、**リクエストログを表示** を選択して、[キーリスト](https://dashboard.stripe.com/apikeys)からテスト環境のキーのログを確認します。

`403 ERR` などのエラーメッセージが表示された場合は、制限付きキーの権限を編集して、失敗したアクションを追加します。

1. キーの横にあるオーバーフローメニュー (⋯) をクリックします。
1. **キーを編集**を選択します。
1. サンドボックスでテストを繰り返し、制限付きキーに正しい権限が割り当てられていることを確認します。

アプリケーションログで Stripe API のエラーを確認してください。リクエストで送信された制限付きキーに適切な権限がない場合、レスポンス本文には、追加が必要な権限を説明するエラーメッセージが含まれます。

### 本番環境の制限付きキーを作成する

テストしたテスト環境のキーと同じ権限を持つ新しい制限付きキーを、本番環境で作成してください。

### 本番環境で制限付きキーを使用するよう設定する

ステージング環境でテストキーを設定したのと同じ方法で、本番環境で新しいキーを使用してください。

### 古いシークレットキーを廃止する

テスト環境ですべてが正常に機能することを確認したら、Dashboard で以前のシークレットキーを[ローテーション](https://docs.stripe.com/keys.md#rolling-keys)するか、[期限切れにし](https://docs.stripe.com/keys.md#delete-secret-key)てください。これにより、今後そのキーを誰も使用できなくなります。シークレットキーに戻せるよう安全期間を設けたい場合は、有効期限を遅らせることもできます (最大 7 日間)。

## 制限付き API キーに権限を割り当てる

制限付きキーは、最小権限の原則に従って、特定のユースケースに合わせて設定できます。つまり、キーには、役割を果たすために必要な最小限の権限のみを付与し、それ以上は付与しないようにする必要があります。ここでは、権限を割り当てるための実用的な方法をいくつか紹介します。

### リクエストログを監査して権限を判断する

1. Dashboard の [API Keys](https://dashboard.stripe.com/apikeys) ページに移動してください。
1. 設定する制限付きキーを見つけてください。
1. キーの横にあるオーバーフローメニュー (⋯) をクリックします。
1. **View request ログ** をクリックすると、そのキーで行われたすべてのリクエストを確認できます。

制限付きキーを使ったテスト中にアプリケーションが使用した API エンドポイントを確認し、アプリケーションが使用したリソースと、それらに対して読み取りまたは書き込みを行ったかどうかを正確に把握してください。

- `GET` リクエストは読み取りです
- `POST` リクエストと `DELETE` リクエストは書き込みです

アプリケーションがテストで正常に動作した場合は、リクエストログで成功したコールの一覧を作成し、その一覧を制限付きキーに付与した権限と比較できます。キーで使用していない権限は削除できます。キーの権限を編集するには、以下のようにします。

1. オーバーフローメニュー (⋯) をクリックします。
1. **Edit key** をクリックします。

アプリケーションが正しく動作しない場合は、キーのリクエストログを絞り込んで失敗したリクエストを表示し、キーメニューでキーの権限を編集して、対応する Stripe API の権限を追加できます。

### コードを確認する

コードベースで Stripe SDK 呼び出しを検索することで、必要な権限の一覧を作成できます。各呼び出しを Dashboard の対応する権限に対応付けることができます。以下に例を示します。

- `PaymentIntent.create(...)` → **PaymentIntents: Write**
- `Customer.retrieve(...)` → **Customers: Read**
- `Dispute.list(...)` → **Disputes: Read**

次に、見つかったものだけに一致するように、制限付きキーの権限を設定します。

### 広範な権限から開始し、不要なものを削除する

最初は制限付きキーに広範な権限を付与し、その後、キーの使用状況を確認して余分な権限を削除できます。

サンドボックスで、API キーメニューから制限付きキーを作成します。利用可能な権限はカテゴリーごとに分類されています。Stripe API の使用に Stripe Billing などの特定のカテゴリーが含まれないことがわかっている場合は、そのカテゴリーで **None** を選択できます。それ以外の場合は、Stripe API の使用に関連するカテゴリーで **Write** を選択します。**Write** 権限には **Read** 権限も含まれます。キーに API リソースへの書き込み権限があれば、そのリソースの読み取りも可能です。

上記の説明に従って、テスト環境の制限付きキーを使用してアプリケーションをテストし、アプリケーションがそのキーを使って Stripe API リクエストを送信するようにします。Stripe API を使用するアプリケーション内のすべてのコンポーネントをテストします。

## サービスまたはユースケースごとに 1 つの制限付きキーを使用する

Stripe API を使用するサービスが複数ある場合 (たとえば、請求サービス、レポートサービス、Webhook ハンドラーなど) は、サービスごとに個別の制限付きキーを作成し、各キーにはそのサービスに必要な Stripe API 権限のみを付与します。権限を分けることで、いずれかのサービスが侵害された場合でも、キーの乗っ取りによる影響を抑えられます。