API キー

3 種類の資格情報、3 種類の脅威モデルがあります。

pk_ — Publishable

• ブラウザに配布することを前提に設計されています。署名付き B2B リクエストのたびに X-Client-ID ヘッダーとして送信され、 クライアント側でチェックアウトを開くために SDK バンドルにも 埋め込まれます。
• あなたのアカウントを識別できますが、セッションの作成、他の マーチャントのデータの読み取り、破壊的な操作のトリガーはできません。
• Publishable キーの漏洩は 低深刻度 の事象です。

sk_ — シークレット（HMAC 署名鍵）

• すべての B2B API 呼び出し向けの HMAC-SHA256 署名鍵です — 認証 を参照してください。
• ネットワーク越しに送信されることはありません。送信されるのは リクエストごとに導出された署名だけです。したがって心配すべきは トランスポート層ではなく、ストレージ 層（環境変数、Git、ログ） での漏洩だけです。
• サーバー限定です。ブラウザバンドル、公開リポジトリ、 スクリーンショット、チャットメッセージに現れることは決して あってはなりません。
• シークレットの漏洩は 高深刻度 の事象です。

whsec_ — Webhook 署名シークレット

• 当方からあなたのサーバーへの 受信 Webhook 配信の署名を 検証するために使用します。 署名検証 を参照してください。
• Webhook エンドポイントごとに別々です — 3 つのエンドポイントを 登録していれば、3 つの異なる whsec_ シークレットを持つことに なります。環境はプレフィックスにエンコードされます: whsec_live_… / whsec_test_…。
• サーバー限定です。sk_ と同様、ネットワーク越しに送信される ことはなく、ローカルで HMAC を検証するためだけに使われます。
• ローテーションには 24 時間の猶予ウィンドウがあります。 Rotate をクリックすると、新しいシークレットに加えて古い シークレットも 24 時間受け入れられ続けます（配信には X-Signature と X-Signature-Prev の両方が付きます）。これにより、 トラフィックを止めずに検証ロジックを再デプロイできます。
• 既存シークレットの再表示 も可能です。新規の 2FA 検証で ゲートされ、監査ログに記録されます — シークレットを紛失し、 かつローテーションが許容できない場合のためのものです。 ダッシュボードのデフォルトの姿勢は「ローテーションする、 再表示しない」です。
• Webhook シークレットが漏洩すると、攻撃者があなたの URL に 偽のイベントを送れるようになります。イベントペイロードを どれだけ信頼しているかによって 中〜高深刻度 です。

スコープ

シークレットキーはスコープを持ちます。ダッシュボードでは以下の スコープバンドルのいずれかでキーを発行できます。

デフォルトで発行される「フルアクセス」キーはこの 4 つすべてを 持ちます。用途別のキーを発行することは依然として良い習慣です — 意図を明文化でき、強制が実装されたときにすぐ対応できます — ただし スコープをセキュリティ境界として扱う前に、下記の注意事項を読んで ください。

ローテーション

1. 新しいキーを生成する。 Dashboard → Developers → API keys → + Add key。スコープを選びます。ダッシュボードは シークレットを 1 度だけ 表示します — すぐに保存してください。
2. 環境変数を新しい値にロールします（すべての環境で）。 デプロイします。
3. トラフィックを確認する。 ダッシュボードにはキー別の リクエスト数がリアルタイムで表示されます。古いキーの件数が ゼロになるまで待ちます。
4. 古いキーを失効させる。 同じ画面 → ケバブメニュー → Revoke。

緊急時の失効

キーが漏洩した場合（Git の履歴、公開バンドル、ログに残った スタックトレース、パートナーのペネトレーションテストレポートなど） — 一部のリクエストが失敗する犠牲を払ってでも、直ちに失効させて ください。攻撃者に有効な資格情報を握らせたままにするより、明確に 失敗させる方が良いのです。

手順:

1. Dashboard → Developers → API keys → [key] → Revoke now。 効果は即座で、猶予期間はありません。
2. 代替のキーを発行し、デプロイします。
3. 最近のアクティビティを監査します — ダッシュボードには過去 30 日間のキー別リクエストが IP とアクセス先エンドポイントと ともに表示されます。

侵害が 1 つのキーにとどまらないと思われる場合は、 [email protected] に連絡して以下を依頼してください:

• マーチャントアカウントの完全な監査ログのエクスポート
• Webhook シークレットの一括ローテーション
• 調査中のアカウントの一時凍結（任意）

保存のベストプラクティス

• 環境変数のみ。 .env.example に “REPLACE ME” と書いてある 場合でも、シークレットを Git にコミットしないでください。
• 環境ごとのキー。 dev / staging / prod で異なる sk_test_… と sk_live_… を使い、シークレットマネージャー （AWS Secrets Manager、Vault、Doppler、…）から取得してください。
• 環境変数へのアクセスを制限する。 Kubernetes では ConfigMap ではなく Secret としてマウントしてください。 Vercel / Netlify ではプロジェクト全体のグローバル変数ではなく 環境変数スコープを使ってください。
• ボディ付きのリクエストをログに残さない。 デバッグ時でも 同様です — X-Signature の HMAC 署名は使い切りですが、ビジネス ペイロードには PII が含まれる場合があります。

現時点でサポートしていないもの

• ❌ シークレットキーの IP アローリスト。ロードマップにあります。
• ❌ OAuth 風のユーザー単位スコープトークン。 現在のキーモデルは ユーザー単位ではなくマーチャント単位です。
• ❌ 自動キーローテーション（例: プラットフォームが強制する 週次ローテーション）。現時点では手動です。

次に

• 認証 — B2B 呼び出しの正確な 署名アルゴリズム。
• Webhook → 署名検証 — 受信イベントで whsec_ がどう使われるか。