# API キー 3 種類の資格情報、3 種類の脅威モデルがあります。 ## `pk_` — Publishable - ブラウザに配布することを前提に設計されています。署名付き B2B リクエストのたびに `X-Client-ID` ヘッダーとして送信され、 クライアント側でチェックアウトを開くために SDK バンドルにも 埋め込まれます。 - あなたのアカウントを識別できますが、セッションの作成、他の マーチャントのデータの読み取り、破壊的な操作のトリガーはできません。 - Publishable キーの漏洩は **低深刻度** の事象です。 ## `sk_` — シークレット（HMAC 署名鍵） - すべての B2B API 呼び出し向けの HMAC-SHA256 署名鍵です — [認証](https://docs.infraio.xyz/ja/api-reference/authentication) を参照してください。 - ネットワーク越しに送信されることはありません。送信されるのは リクエストごとに導出された署名だけです。したがって心配すべきは トランスポート層ではなく、*ストレージ* 層（環境変数、Git、ログ） での漏洩だけです。 - サーバー限定です。ブラウザバンドル、公開リポジトリ、 スクリーンショット、チャットメッセージに現れることは決して あってはなりません。 - シークレットの漏洩は **高深刻度** の事象です。 ## `whsec_` — Webhook 署名シークレット - 当方からあなたのサーバーへの **受信** Webhook 配信の署名を 検証するために使用します。 [署名検証](https://docs.infraio.xyz/ja/webhooks/signature-verification) を参照してください。 - Webhook エンドポイントごとに別々です — 3 つのエンドポイントを 登録していれば、3 つの異なる `whsec_` シークレットを持つことに なります。環境はプレフィックスにエンコードされます: `whsec_live_…` / `whsec_test_…`。 - サーバー限定です。`sk_` と同様、ネットワーク越しに送信される ことはなく、ローカルで HMAC を検証するためだけに使われます。 - **ローテーションには 24 時間の猶予ウィンドウがあります。** Rotate をクリックすると、新しいシークレットに加えて古い シークレットも 24 時間受け入れられ続けます（配信には `X-Signature` と `X-Signature-Prev` の両方が付きます）。これにより、 トラフィックを止めずに検証ロジックを再デプロイできます。 - **既存シークレットの再表示** も可能です。新規の 2FA 検証で ゲートされ、監査ログに記録されます — シークレットを紛失し、 かつローテーションが許容できない場合のためのものです。 ダッシュボードのデフォルトの姿勢は「ローテーションする、 再表示しない」です。 - Webhook シークレットが漏洩すると、攻撃者があなたの URL に 偽のイベントを送れるようになります。イベントペイロードを どれだけ信頼しているかによって **中〜高深刻度** です。 ## スコープ シークレットキーはスコープを持ちます。ダッシュボードでは以下の スコープバンドルのいずれかでキーを発行できます。 | スコープ | できること | 用途 | | --- | --- | --- | | `read` | 注文、セッション、返金、残高の一覧 / 読み取り | 読み取り専用の統合（分析、BI） | | `write_order` | `read` の全権限 + セッション作成、注文作成、注文キャンセル | ストアフロントのバックエンド | | `write_refund` | `read` の全権限 + 返金作成、返金実行済みのマーク | カスタマーサポートツール | | `webhook_manage` | `read` の全権限 + Webhook エンドポイントの管理 | DevOps ツール | デフォルトで発行される「フルアクセス」キーはこの 4 つすべてを 持ちます。用途別のキーを発行することは依然として良い習慣です。 意図を明文化できるためです。ただし スコープをセキュリティ境界として扱う前に、下記の注意事項を読んで ください。 > **Warning:** > > **スコープはまだ強制されていません。** どのスコープの `sk_` キーが漏れても、 > そのマーチャントの **どの** `/b2b/v1/*` エンドポイントも呼び出せて > しまいます。`read` キーが返金の作成を防がれることはありません。 > 狭いスコープは今のところ漏洩時の被害を **制限しません**: > セキュリティ計画ではすべてのシークレットキーをフルアクセスとして扱い、 > 漏洩の封じ込めには（下記の）迅速なローテーションと失効を > 頼ってください。 ## ローテーション 1. **新しいキーを生成する。** Dashboard → **Developers → API keys** → **+ Add key**。スコープを選びます。ダッシュボードは シークレットを **1 度だけ** 表示します — すぐに保存してください。 2. **環境変数を新しい値にロールします**（すべての環境で）。 デプロイします。 3. **トラフィックを確認する。** ダッシュボードにはキー別の リクエスト数がリアルタイムで表示されます。古いキーの件数が ゼロになるまで待ちます。 4. **古いキーを失効させる。** 同じ画面 → ケバブメニュー → **Revoke**。 > **Warning:** > > 現時点で **自動的なオーバーラップウィンドウはありません** — > キーを失効させると、そのキーで署名された処理中のリクエストは > すべて `401` になります。ローテーションはそれを踏まえて計画して > ください: まず新しいキーをデプロイし、古いキーからトラフィックを > 排出してから失効させます。 ## 緊急時の失効 キーが漏洩した場合（Git の履歴、公開バンドル、ログに残った スタックトレース、パートナーのペネトレーションテストレポートなど） — 一部のリクエストが失敗する犠牲を払ってでも、直ちに失効させて ください。攻撃者に有効な資格情報を握らせたままにするより、明確に 失敗させる方が良いのです。 手順: 1. **Dashboard → Developers → API keys → [key] → Revoke now。** 効果は即座で、猶予期間はありません。 2. 代替のキーを発行し、デプロイします。 3. 最近のアクティビティを監査します — ダッシュボードには過去 30 日間のキー別リクエストが IP とアクセス先エンドポイントと ともに表示されます。 侵害が 1 つのキーにとどまらないと思われる場合は、 contact@lartech.xyz に連絡して以下を依頼してください: - マーチャントアカウントの完全な監査ログのエクスポート - 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 風のユーザー単位スコープトークン。** 現在のキーモデルは ユーザー単位ではなくマーチャント単位です。 - ❌ **自動キーローテーション**（例: プラットフォームが強制する 週次ローテーション）。現時点では手動です。 ## 次に - [認証](https://docs.infraio.xyz/ja/api-reference/authentication) — B2B 呼び出しの正確な 署名アルゴリズム。 - [Webhook → 署名検証](https://docs.infraio.xyz/ja/webhooks/signature-verification) — 受信イベントで `whsec_` がどう使われるか。