SMMパネルReseller API v2キーの発行・管理・失効ベストプラクティス

結論:鍵は「発行して終わり」ではなく、生成から失効までをワンセットで設計する

Reseller API v2キー(下流の再販売者やリセラー企業がプログラムから発注・ステータス確認・残高照会を行うための認証情報)は、漏洩すれば即座に不正発注や残高詐取につながる、パネル運営における最重要の機密情報の一つです。安全に運用するための結論は次の3点に集約されます。

1. サーバー側は生キーを保存せず、ハッシュ値と先頭数文字の「prefix(識別用の接頭辞)」だけを保持する
2. 生キーはユーザーに見せる「その1回」限りとし、以後は二度と画面に出さない
3. 失効(revoke)は物理削除ではなく論理フラグで行い、定期的なローテーションを運用フローに組み込む

これらを最初から設計に組み込んでおけば、万が一キーが漏洩しても被害を「即座に無効化できる範囲」にとどめられます。以下、具体的な手順を見ていきます。

発行・運用の具体的な手順

発行時

生キーは暗号論的に安全な乱数生成器(例: Node.jsのcrypto.randomBytes)で32バイト以上のエントロピーを持たせ、smm_のような接頭辞を付けて「これはAPIキーである」と一目で分かる形式にします。発行直後の画面でのみ生キー全体を表示し、コピーボタンとともに「二度と表示されません」という警告を添えます。以後、DBにもログにも生キーは一切残しません。ユーザーには用途がわかるラベル(例:「Zapier連携用」「自社在庫システム用」)を必ず入力させてください。用途不明のキーは、後述の棚卸しで判断がつかなくなります。

保管

DBにはSHA-256などのハッシュ値のみを保存します。パスワードと異なりAPIキー自体が高エントロピーな乱数であるため、bcryptのような低速ハッシュ関数は不要で、むしろ全リクエストで数十msの遅延を生むコストの方が問題になります。検索用には先頭8文字程度の「prefix」だけを平文でインデックス保存し、認証時はprefixで候補を絞り込んでからハッシュ値を定数時間比較(タイミング攻撃対策)します。

運用中

最終利用日時(lastUsed)を記録し、リセラー自身が「このキーは3ヶ月使われていない」と一覧画面で確認できるようにします。使われていないキーは棚卸しの際に失効候補とします。可能であれば発行時にスコープ(発注のみ/照会のみ等)やIP許可リストを設定できるようにし、最小権限の原則を徹底しましょう。さらにキー単位でレート制限をかけることも重要です。IPアドレス単位の制限だけでは、同一キーを複数拠点で使い回すケースを取りこぼします。

失効・ローテーション

退職・契約終了・端末紛失などのタイミングでは即時失効を案内します。失効は論理削除(revokedAtに日時を記録する方式)で行い、監査ログとして残しましょう。物理削除してしまうと「誰がいつまでそのキーで何をしていたか」の追跡ができなくなります。ローテーション(定期的な鍵の再発行)は「新キー発行→旧キー失効」を一連の操作として扱い、新旧を同時に有効にする猶予期間を設けずに即時切替するか、意図的に数分〜数時間の重複を許容するかを事前にルール化しておきます。重複を許せば切替作業中の連携停止を避けられますが、旧キーの露出時間が延びるというトレードオフがあります。

セキュリティ上の注意点

• 認証失敗のメッセージは常に同一文言にする:「キーが見つかりません」と「失効済みです」を区別して返すと、攻撃者に「かつて実在したキーである」という情報を与えてしまいます。
• 失効・更新操作は必ずテナントと所有ユーザー単位でスコープする: idだけで検索・更新を許すと、他社のキーIDを推測されて誤って操作される危険があります。
• 生キーは絶対にログへ出さない: アプリケーションログ、エラートラッキングツール、URLクエリパラメータへの平文混入は典型的な事故原因です。フォームボディでの送信を基本とし、クエリでの送信は暫定的な互換手段にとどめます。
• 発行・失効の通知を管理者へ飛ばす: メールやチケットで通知する設計にしておくと、なりすましによる不正発行にも気づきやすくなります。

まとめ:次の一歩

Reseller API v2キーは、リセラーがあなたのパネルをプログラムから利用するための「玄関の鍵」です。発行のしやすさと、漏洩時に被害を最小化できる設計は両立できます。まずは自社の鍵管理が「生キーを保存していないか」「失効が論理削除で監査ログに残るか」「lastUsedで棚卸しができるか」の3点を点検するところから始めてください。次のステップとして、キー単位のレート制限とスコープ制御を導入すれば、下流の再販売者に安心して自動発注の窓口を開放できる体制が整います。