Stripe APIキー解説：テスト用と本番用、公開可能キーとシークレットキー、制限付きキーの違い

Stripe のインテグレーションはどれも同じ疑問から始まります。どのキーをどこに置くのか？ Stripe は公開可能キー、シークレットキー、そして制限付きキーを発行するオプションを渡してきます。それぞれにテスト用と本番用があります。間違ったキーを間違った場所に置けば、資金を動かす権限を漏らすか、401 で午後を無駄にするかのどちらかです。本ガイドでは、各 Stripe API キーが何をするのか、どこに保管されるのか、最初のテストモードリクエストをどう送るのか、そして本番キーを共有物からどう遠ざけておくのかを扱います。まず一般的な概念については、API キーとは何かから始めてください。以下の内容はすべて Stripe の API キーのドキュメントに準拠しており、2026年9月時点で確認済みです。

Stripe API キーはダッシュボードのどこにあるか

dashboard.stripe.com/apikeys で API キーページを開きます。ダッシュボードの「開発者」の下にあり、表示中のアカウントまたはサンドボックスのキーを表示します。トグルでサンドボックスモードと本番モードを切り替えると、キーの一覧もそれに合わせて変わります。

ページには 2 つのリストがあります。

標準キーには公開可能キーとシークレットキーが入ります。
制限付きキーには、スコープ付き権限で作成したキーが入ります。

表示される範囲はモードによって異なります。サンドボックスではいつでもすべてのキーを表示できます。本番モードでは、自分で作成したシークレットキーは作成時に一度だけ表示されます。ダイアログを閉じる前にボルトにコピーしてください。失えばローテーションするしかありません。本番モードで再度表示できるのは、Stripe が生成したデフォルトキーだけです。

ページに表示されないものがあります。Webhook 署名シークレットです。これらは Webhooks の下にエンドポイントごとに存在し、API キーではありません。

公開可能キーとシークレットキー

その名前が信頼境界を表しています。

キー	プレフィックス	公開しても安全か	できること
公開可能	`pk_test_` / `pk_live_`	はい	アカウントを識別し、Stripe.js、Elements、モバイル SDK でカード情報からトークンと PaymentMethod を作成する
シークレット	`sk_test_` / `sk_live_`	いいえ	すべて: チャージの作成、返金の発行、顧客データの読み取り、支払いのトリガー
制限付き	`rk_test_` / `rk_live_`	いいえ	付与したリソースと権限のみ

公開可能キーはブラウザまたはモバイルアプリに置くものです。カード番号をトークンに変えるだけで、それ以外はほとんどできません。チャージを作成したりアカウントデータを読み取ったりはできないため、フロントエンドコードに含めて出荷するのは想定内です。

シークレットキーはサーバーに置くもので、他のどこにも置きません。Stripe のガイダンスは変わりました。ドキュメントは現在「新しいユースケースでシークレットキーを使うことは推奨しない」と述べ、代わりに制限付きキーを指し示しています。無制限のシークレットキーは今も動作しますが、デフォルトではなく非常手段として扱ってください。

テストモードキーと本番モードキー

Stripe は 2 つの別世界を運用しており、それぞれに独自のキーセットがあります。テストキー（新しいドキュメントではテスト側をサンドボックスと呼びますが、プレフィックスは今も _test_ です）はシミュレートされたオブジェクトを返します。偽の顧客、偽の PaymentIntent、コマンド一つで成功または拒否するテストカード、そして実際のお金の移動はありません。本番キーはカードネットワークに到達し、実際の資金を動かします。

この分離は厳格です。sk_test_ で作成した顧客は sk_live_ から見れば存在せず、その逆も同様です。この混線に対する Stripe のエラーコード livemode_mismatch は明快です。「テストモードと本番モードの API キー、リクエスト、オブジェクトは、対応するモード内でのみ利用できます。」

そこから 2 つの実務ルールが導かれます。

ビルドとテストは完全に sk_test_ または rk_test_ に対して行います。Stripe は新しいインテグレーション用に、設定とデータを分離しておくため別の汎用サンドボックスを推奨しています。
本番への切り替えはコード変更ではなく設定変更です。サーバーは環境変数またはボルトからキーを読み取り、本番化とはその値を変えることを意味します。

すべての API レスポンスには livemode ブール値が含まれます。テストでこれをアサートしてください。誤ったキーでのデプロイに対する最も安価な防御策です。

制限付きキーと最小権限

制限付き API キー（Stripe は RAK と略します）は、権限マスクを備えたシークレットキーです。作成する際、リソースグループごとに権限を選びます。None、Read、Write のいずれかです。すべてデフォルトは None です。Write は Read を含み、HTTP との対応は単純です。GET には Read が必要で、POST と DELETE には Write が必要です。

作成するには、API キーページで 制限付きキーを作成 をクリックし、事前設定された権限セットを選ぶかゼロから始め、名前を付けて権限を設定し、二要素認証のプロンプトを完了します。本番モードで自分で作成したシークレットキーと同様、値は一度しか表示されません。

制限付きキーガイドは、サービスごとに 1 つのキーを提案しています。請求サービスには Invoices と Customers の Write を、レポートジョブには Charges と Disputes の Read を、といった具合です。1 つのサービスが侵害されても、攻撃者はそのキーの権限に閉じ込められます。読み取り専用の Disputes キーはチャージを作成したり支払いに触れたりできません。

新しいキーにはサンドボックスで広い権限を与えてテストスイートを実行し、その後、キーのリクエストログ（オーバーフローメニューの リクエストログを表示）を開き、トラフィックのなかった権限をすべて削ぎ落とします。Stripe では、自律型 AI エージェント向けのキーにタグを付け、支払いや返金の承認ルールの対象にすることもできます。単なるシークレットキーではなく、その経路を使ってください。

curl と Python で最初のリクエスト

Stripe は HTTP Basic 認証で認証します。キーがユーザー名で、パスワードは空です。末尾のコロンは curl にプロンプトを出さないよう指示します。

export STRIPE_API_KEY=sk_test_...   # your sandbox secret key

curl https://api.stripe.com/v1/payment_intents \
  -u "$STRIPE_API_KEY:" \
  -d amount=2000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true"

レスポンスは PaymentIntent で、id は pi_ で始まり、status: "requires_payment_method"、livemode: false です。最後のフィールドが、テストキーを使ったことを裏付けます。

Stripe は -H "Authorization: Bearer $STRIPE_API_KEY" も受け付けます。これは Apidog やほとんどの HTTP クライアントが使う形式です。どちらも同じキーを運びます。どちらのスタイルが自分のスタックに合うか不明なら、API キーとベアラートークンの比較でトレードオフを説明しています。リクエストは HTTPS 経由でなければなりません。平文 HTTP は認証リファレンスに従い、即座に失敗します。

Python では、現在の SDK パターンは環境からキーを読む StripeClient です。

import os
import stripe

client = stripe.StripeClient(os.environ["STRIPE_API_KEY"])

intent = client.v1.payment_intents.create({
    "amount": 2000,
    "currency": "usd",
    "automatic_payment_methods": {"enabled": True},
})
print(intent.id, intent.livemode)  # pi_..., False

ファイル内にキー文字列は現れません。同じコードが、環境が提供するものに応じてテストまたは本番に対して実行されます。

コーディングエージェントに Apidog CLI で Stripe キーをテストさせる

curl はキーが一度動くことを証明します。コーディングエージェントはそれを Apidog CLI を通じて繰り返し可能なチェックに変え、キーを共有プロジェクトの外に保つことができます。一度セットアップします（トークンはアカウント設定、API アクセストークンにあります）。

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

次にエージェントに 1 つのプロンプトを与えます。

Use Apidog CLI on project <id>. Create a "Stripe Test" environment with base URL
https://api.stripe.com. Add POST /v1/payment_intents with Bearer auth from
{{stripe_secret_key}} and a form-urlencoded body: amount=2000, currency=usd.
Create a test case asserting status 200, an id starting with pi_ and
livemode false, then run it and summarize any failures.

実行されるコマンド（Apidog CLI 2.2.7 で確認済み）:

apidog environment create "Stripe Test" --project <id> --base-url https://api.stripe.com
apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file payment-intents.json
apidog cli-schema validate test-case-create --file pi-case.json
apidog test-case create --project <id> --file pi-case.json
apidog run --test-case <caseId> --project <id> -e <envId> \
  --env-var "stripe_secret_key=$STRIPE_API_KEY" -r cli,json

プロンプトでフォームエンコーディングを指定しているのは、Stripe の v1 エンドポイントが JSON を受け付けないからです。livemode アサーションはあなたのトリップワイヤーです。もし誰かが本番キーでケースを実行すれば、2 回目のリクエストが出る前に失敗します。CI では、同じ apidog run 行がパイプラインのシークレットストアからキーを読み取ります。Apidog CLI CI/CD パイプラインガイドにコピー&ペーストできる版があります。リクエスト定義は共有されますが、本番の資格情報が共有されることは決してありません。

キーのローテーションと漏洩時の対処

Stripe 自身のキー取り扱いガイドは率直です。リポジトリにコミットされたもの、チャットに貼られたもの、ログに出力されたものは、誰かが見たかどうか確信がなくても侵害されたと見なしてください。

ローテーションはダッシュボードに組み込まれています。キーのオーバーフローメニューから キーをローテーション を選び、古いキーの有効期限を設定し、置き換え用のキーをコピーします。猶予期間中（最大 7 日間）は両方が機能するため、段階的に展開し、リクエストログで取り残しを監視できます。今すぐ を選ぶと古いキーは即座に失効します。

シークレットキーまたは制限付きキーが漏洩した場合:

短い有効期限で即座にローテーションします。
それを使用していたすべてのサーバーを更新し、リクエストログでトラフィックを確認してから、古いキーを失効させます。
Workbench で最近のアクティビティを確認し、あなたのインテグレーションが行わないはずのものがないか調べます。見覚えのないコネクトアカウント、開始していない支払い、新しい銀行口座などです。
不審な支払いを一時停止し、すでに送金済みのものは取り消し、不正なチャージは迅速に返金してディスピュートを未然に防ぎます。
他のキーもローテーションします。1 つ漏洩したなら、漏洩した経路はもっと多くを見たと考えるべきです。

Stripe は露出したキーをスキャンして通知し、時にはプロアクティブにキーを無効化することもありますが、検出は保証されません。リポジトリと CI 設定で sk_live_ と rk_live_ を検索するのは 5 分の監査ですし、pre-commit フックのシークレットスキャナが次に漏れるのを防ぎます。Stripe がシークレットキーを求めることは決してないので、それを要求するメッセージはフィッシングです。

よくある Stripe API キーエラー

症状	意味	修正
`401` “No valid API key provided”	キーが欠落、不正な形式、または失効している	ヘッダーを確認し、キーがローテーションされていないことを確かめる
`api_key_expired`	キーがローテーションまたは失効している	ダッシュボードから現在のキーを取得する
`secret_key_required`	サーバーサイドのエンドポイントに `pk_` キーを送信した	バックエンドでは `sk_` または `rk_` を使う
存在すると分かっている id で `resource_missing`	モードが違う: テストキーで本番オブジェクトにアクセス、またはその逆	キーのモードとオブジェクトを一致させる
`403` “doesn’t have permissions to perform the request”	制限付きキーにそのリソースの Read または Write がない	キーの権限を編集する。エラー本文が不足しているものを示す
`livemode_mismatch`	1 つのリクエストでテストと本番のキーまたはオブジェクトを混在させている	各環境を完全に 1 つのモードに保つ

401 と 403 のケースは Python SDK では stripe.AuthenticationError と stripe.PermissionError に対応し（エラーリファレンス参照）、個別にキャッチできます。もう 1 つ分かりにくいケースがあります。180 日間トランスファーや支払いを作成していない本番キーは、それらのアクションが制限され、キーに アクセスを復元 オプションが表示されます。

FAQ

Stripe の公開可能キーをフロントエンドコードに置いても安全ですか？

はい。pk_ キーはカード情報をトークン化しますが、チャージの作成、顧客の読み取り、資金の移動はできません。サーバーサイドに置くのはシークレットキーと制限付きキーだけです。

テストモードで制限付きキーを使えますか？

はい。制限付きキーは両モードに存在します（rk_test_ と rk_live_）。Stripe はまずテスト版を調整し、その後同じ権限で本番キーを作成することを推奨しています。

Webhook 署名シークレットは API キーと同じですか？

いいえ。署名シークレットは Webhook エンドポイントごとに発行され、受信イベントが Stripe から来たことを検証するだけです。これらは API キーページではなく Webhooks の下にあります。それらを配線する場合は、CI で Stripe Webhook をテストする方法をご覧ください。

本番でテストキーを使うとどうなりますか？

リクエストは成功しますが、カードは請求されず、お金も動きません。すべてのオブジェクトで livemode が false で返るため、そのフィールドへのアサーションが顧客より先にミスを捕まえます。

まとめ

公開可能キーはクライアントに、シークレットキーと制限付きキーはサーバーに置き、テストと本番は決して混ぜず、スコープを絞れるなら常にシークレットより制限付きが勝ります。本番キーはボルトに保管し、テストキーは実行時に Apidog CLI に渡し、エージェントが書くすべてのテストケースに livemode アサーションを入れておきましょう。