APIキーのローテーションUX：スコープ、セルフサービスキー、ログ

なぜ実際のプロダクトでAPIキーが問題になるのか

APIキーは最初は単純です：キー1つ、連携1つで終わり。しかし問題が出てくるのは、その同じキーが共有されたスプレッドシートやSlack、あるいはもはや誰のものでもないスクリプトにハードコーディングされるときです。一度キーがあちこちにコピーされると、誰が使っているのか、なぜ使っているのかといった基本的な問いに答えられなくなります。

変更されないキーもよくある罠です。1つの漏洩したキーが数か月にわたる悪用、予期しない請求、あるいはデータ流出につながることがあります。何も「悪い」ことが起きなくても、古いキーはあまりにも多くの場所に残っているため、安全に削除できないリスクを生みます。

良いキー管理はセキュリティだけの話ではありません。事故を減らし、サポート作業も減らします。顧客が自分のキーを見て制限し、安全に置き換えられるようになると、チームは手動でリセットしたり当て推量で対応する必要がなくなります。

「セルフサービス」は役割によって意味が変わるべきです。管理者はワークスペース全体の管理が必要で、一般ユーザーは自分が所有するもの、あるいは管理者が委譲したものだけを操作できるべきです。目標は責任の明確化と境界の明瞭化で、複雑な権限迷路を作らないことです。

セキュリティと使いやすさは両立しなければなりません。UXが使いにくいと、人は回避してあちこちで「マスターキー」を使い回します。実用的なシステムは、安全な選択が最も簡単な道になるようにします：

• アプリや連携ごとにキーを作る。会社単位ではなく。
• 各キーができること（と使用できる場所）を制限する。
• 誰が作成したか、いつ最後に使われたかを表示する。
• ローテーションを普通でストレスの少ない操作にする。

例：パートナーが「APIアクセス」を求めてきたとします。唯一の選択肢がフルアクセスキーなら、意図以上の権限を渡すことになります。セルフサーブのフローは、パートナーの役割に合った狭いキーを発行できるようにし、それ以外は許可しないようにすべきです。

基本：キー、スコープ、所有者、環境

キー管理は関係者に名前を付け、責任を明確にすると楽になります。多くのプロダクトでは次のような役割が繰り返し出てきます：アカウント所有者（ルール設定と支払い）、管理者（ワークスペース全体のアクセス管理）、開発者（コードでキーを使いローテーションする）、サポート（「なぜ失敗したのか？」に答える）、監査担当（アクセスが管理され追跡可能であることを確認する）。

キーは単なる秘密文字列ではありません。文脈を持った権限付きの資格情報です。キーを共有パスワードのように扱うと、ローテーションやインシデント対応、基本的なデバッグで痛い目を見ます。

早い段階でいくつかのコアオブジェクトを定義しましょう：

• キー：シークレット値とメタデータ（作成後は生のシークレットを保存しない）。
• スコープ：許可されたアクションの名前付きセット（例：注文の閲覧、請求書の作成など）。
• 所有者：キーの責任者となる特定のユーザーまたはサービスアカウント。
• 環境：キーが使える場所（dev、staging、production）。
• 有効期限：いつ無効になるか、またはいつローテーションが必要か。

失敗モードは予測可能です：キーがリポジトリやチャットで漏れる、スコープが「とりあえず動くように」と広くなりすぎる、どのキーがリクエストを行ったか分からない。最後の問題はサポート負荷を増やし、セキュリティ作業を遅らせます。

v1でサポートしないことも決めておきましょう。多くのチームは組織全体で共有するキー、期限無しの「永久」キー、全ての環境で動作するキーを避けます。後で監視するより、設計上そうした状態を不可能にするほうが簡単です。

人が実際に使う最小権限スコープの設計

最小権限は、ユーザーが数秒で正しいスコープを選べるときにだけ機能します。セキュリティの専門家でなければ理解できないようでは、ユーザーは「全アクセス」を選んで先に進んでしまいます。

まず、内部サービス名ではなく人が説明するであろうアクションをリストアップしましょう。「請求書を閲覧する」はわかりやすいです。billing.readのような名前も構いませんが、UIで平易な説明が付いていることが重要です。特にローテーション時に、置き換えキーが元のキーと同等であるという自信が必要だからです。

スコープセットは小さく、安定して、実際の仕事に基づいてグループ化してください。例えば：

• レポーティング（請求書、顧客、支払いの閲覧）
• カスタマーサポート（顧客情報の閲覧、返金の実行）
• 注文管理（注文の作成、ステータス更新、キャンセル）
• Webhook（エンドポイントの作成、シークレットのローテーション）
• 管理（ユーザー管理、APIキー管理）

50個もの小さなトグルは避けましょう。長いリストは通常、スコープがコード構造をそのまま反映していて、人々の作業の仕方に合っていないことを示しています。

安全なデフォルトを用意しましょう。一般的なユースケースに対して「推奨バンドル」を提示し、各バンドルが何をするかを明確にします。例えば「会計連携」バンドルは請求書と支払いの閲覧を既定で許可し、返金はオフにする、といった具合です。上級者にはカスタマイズを残します。

リスクの高いスコープには意図的に摩擦を加えます。追加確認ステップ、管理者のみが付与できる、時間限定の権限昇格、または監査ログに保存される理由の必須入力などが考えられます。

例：パートナーが請求書を自分のシステムに同期したい場合、彼らには「請求書の閲覧」と「顧客の閲覧」を与え、返金や請求管理は与えないべきです。後で返金が必要になった場合は、その単一の権限だけを申請・承認できるようにします。

キー管理UX：ミスを防ぐ画面と言葉選び

デフォルトのページは一つの問いに素早く答えるべきです：「今どんなキーが存在していて、安全か？」。シンプルな表が最も有効なことが多い：キー名、環境、状態（有効、期限切れ、取り消し）、最終使用時刻、簡単なスコープの要約。空の状態（まだキーがない場合）は教える内容にし、責めるような表示にしない：「まだキーはありません。特定のアプリやパートナー用に、その必要なスコープだけを与えたキーを作成しましょう。」

キー作成はランダムな秘密を生成する感じではなく、権限を設定する操作のように感じさせましょう。フローは短くし、平易なラベルを使い、つまずきやすい場所には小さなヘルパーテキストを入れます。

良い作成フォームには通常次が必要です：

• 名前（必須）：「Payroll dashboard (prod)」のように具体的な名前が「Key 1」より優れます。
• 環境（必須）：テストと本番が明確に分かれていること。
• スコープ（必須）：安全なデフォルトを示し、ユーザーが追加できるようにする。
• 有効期限（任意だが推奨）：「90日」が簡単なプリセットになります。
• 作成者 / 所有者（自動）：あとで連絡できる人を表示します。

シークレットを生成したら一度だけ表示し、その理由を平易に説明します：「セキュリティのため、作成後はハッシュのみを保存します。今のうちにコピーしてください。後で見ることはできません。」コピーのための明確なアクションを一つ用意し、「安全な場所に保存しました」のような軽い確認を入れます。

取り消し（Revoke）とローテーションは見つけやすく、誤操作しにくくします。「Manage」メニューの背後に置き、影響が明確な表現を使います：

• Revoke："直ちに無効になります。これを使うアプリは失敗します。"
• Rotate："新しいキーを作成し、安全に切り替えた後に古いキーを取り消せます。"

ローテーションをサポートする場合、ガイドダイアログが役に立ちます：古いキーのラベル、新しいキーのラベル、切り替え前に呼び出し元を更新するリマインダーを表示します。

サポートが常に聞く質問に答える利用ログ

何かが壊れたとき、サポートはたいてい同じことを尋ねます：どのキーが使われたか、何を試みたか、何が変わったか。良いAPI利用ログはサーバーログを掘り下げなくてもその答えを明白にします。

有用なログエントリは小さく具体的で、一貫したフィールドを持ち、スキャンやフィルタがしやすいものです：

• タイムスタンプ（タイムゾーン付き）
• キーID（完全なシークレットではない）とキー所有者
• エンドポイントまたはアクション名（可能なら人にわかりやすく）
• 発信元IPとUser-Agent（あれば）
• 結果（成功、スコープでブロック、認証失敗、レート制限、サーバーエラー）とレスポンスコード

ログをキーの詳細ページに紐づけましょう。二つの小さな指標が多くのチケットを防ぎます：First seen（キーが初めて使われた時）とLast used（直近のリクエスト）。キーが「未使用」と表示されれば削除候補です。最後に使われたのが2年前なら、次のローテーションで生き残るべきではありません。

v1ではエクスポートよりフィルタが重要です。フィルタはシンプルで予測可能に：時間範囲、状態（成功／ブロック／失敗）、アクション／スコープ、環境。

保持期間は単なるストレージの問題ではなくプロダクトの判断です。多くのチームはUIでは30〜90日を初期表示にし、管理者のみより長い履歴を見られるようにします。ユーザーがログが「欠けている」と誤解しないよう、画面で明示しましょう。

顧客を壊さない安全なローテーションモデル

ローテーションは予測可能に感じられるときにだけ機能します。単純なポリシーを公開して、次の二つに答えましょう：キーをどのくらいの頻度で回すのか（スケジュール）、そしてどのイベントで即時ローテーションが必要か（イベント駆動）。スケジュールされたローテーションは例えば90日ごと、イベント駆動は「従業員の退職」「キーがチケットに貼られた」「異常な利用のスパイク」などです。

最も安全なのはオーバーラップモデルです。顧客に一瞬でキーを差し替えさせるのではなく、新しいキーを作成して古いキーを一定期間残し、その後古い方を退役させます。

実用的なフロー：

• 新しいキーを作成し「有効」にする。
• 古いキーも有効のままにし、「まもなくローテーション」とラベリングする。
• 顧客がクライアントを更新し、呼び出しが成功することを検証する。
• 顧客が「ローテーション完了」をクリックするか、古いキーが自動で期限切れになる。
• 古いキーは「取り消し（Revoked）」となり再度有効化できない。

猶予期間は重要ですが明確でなければなりません。リストビューに有効期限を表示し、事前に警告を出します（例：14日、3日、24時間）。「まもなく期限切れ」などの曖昧な文言は避け、「このキーは1月30日 10:00 UTCに無効になります」といった具体的な表現を使いましょう。

レート制限やロックアウトは正しい行動を罰することなくアカウントを保護するべきです。多くのクライアントはネットワークタイムアウト後にリトライするため、少数の失敗でロックするのは誤アラームの原因になります。ルールは理解しやすくしましょう：

• レート制限はキーごと、IPごと、アカウントごとで分けて設定する。
• 401エラーはタイムアウトと別に扱う。
• まず警告を出し、一時的にスロットルし、その後新しいキーを要求する。
• UIには理由を必ず表示する：「120 req/minのためスロットルされています」。

例：パートナーが二つのリージョンからAPIを呼んでいるとします。ローテーション中は両方のキーが7日間有効なので、深夜の切り替えやサポートチケットなしで安全にデプロイできます。

監視とアラート：何を表示し、何を通知するか

良い監視は「セキュリティ見せかけ」ではなく、一つの問いに素早く答えることにあります：このキーは所有者が期待する使い方をしているか？

キー一覧には人が素早くスキャンできるステータスチップを表示します。「Active」「Revoked」は明快ですが、「Expiring soon」も驚きを防ぎます。「Last used」タイムスタンプと「Never used」も加え、チームが古いキーを安心して削除できるようにします。

ログビューは単なる生のリクエストではなく、パターンを強調すべきです。複雑なグラフは不要で、いくつかの適切な信号で大半の問題を検出できます：

• リクエストや失敗の急増（特に多数の401）
• 新しいIPレンジや新しい国からの初めてのアクセス（検出できる場合）
• しばらく静かだったキーが突然動き出す

通知は稀で実行可能であるべきです。すべてにアラートを出すとユーザーはミュートしてしまい、本当に重要な通知を見逃します。実用的なv1のセット例：

• キーの期限が近い（例：7日と1日）
• 長期間の非アクティブ後の初回使用
• 短時間で多数の401発生

センシティブなスコープには、作成・ローテーション・拡張の前にMFAや承認ステップのような強いゲートを追加する価値があります。影響が現実的に大きい箇所に限定して適用しましょう。

バックエンドとデータモデル：保存すべきもの（と保存すべきでないもの）

優れたUIでも、バックエンドが間違ったデータを保存していれば失敗します。目標はシンプル：キーをデフォルトで安全にし、監査しやすく、誤用しにくくすることです。

小さく明確なデータモデルから始めましょう。「誰がいつ何をなぜしたか」に答えられる十分なフィールドを保持しつつ、データベースをガラクタ置き場にしないことが重要です。

含めるべきコアテーブル

実用的な最小構成は：

• api_keys：id、owner_id、environment、status（active/revoked）、created_at、last_used_at、expires_at（任意）、key_prefix、secret_hash、rotated_from_key_id（任意）
• scopes：id、name、description、risk_level（任意）
• api_key_scopes：api_key_id、scope_id
• audit_events：actor_id、action、target_type、target_id、metadata、created_at

スコープモデルは安定させておきましょう。スコープの名前変更や削除は統合を壊し、ログを混乱させる可能性があります。

生のシークレットは絶対に保存しない

APIキーはパスワードと同じ扱いにしてください。作成時に一度だけ表示し、その後は一方向ハッシュ（各キーごとのソルトを含む）だけを保存します。サポートやUX用に短い非機密の識別子（プレフィックス、例：「live_2F9K…」）を保存してキーを判別できるようにします。

ローテーションでは新旧キーの関係（rotated_from_key_id）を保存しましょう。これで古いシークレットを保持せずに履歴を追えます。

監査トレイルとアクセス制御

重要な変更はすべて監査イベントを発行するべきです：作成、スコープ変更、ローテーション、取り消し、「ログ閲覧」など。誰が何をできるかを事前に決めます。一般的な設定は、管理者はすべてのキーを管理・全ログを閲覧可能、開発者は自分のキーを管理・自分のログを閲覧可能、サポート／閲覧専用ロールはシークレットを見たりスコープを変更したりできない、というものです。

セキュリティリスクとサポート負荷を増やす一般的なミス

ローテーションをサポート地獄に変える最速の方法は、安全でない選択を普通の選択肢に見せるUIを出すことです。多くの問題は予測可能な罠から発生します。

過度に寛容なデフォルト

デフォルトで「何でもできる」キーを出すと、多くの人はそれを狭めることなく本番に使ってしまいます。

より安全なパターンは最小限のデフォルトスコープを提供し、何かが失敗したときに明確なエラーを返すことです（例：「missing scope: invoices.read」）。もし「全アクセス」オプションを残すなら、注意を促す明示的な選択にしてください。

正体不明のキーと不可解な障害

キーには所有者と目的が必要です。それがないと「どのキーが壊しているの？」や「これを削除してよいか？」というチケットが後から発生します。

作成時に次の二つの小さな入力を求めましょう：

• 所有者（人またはチーム）
• 目的（「Zapier連携」や「Partner ABC sandbox」のような短いラベル）

ローテーションはまたよく障害を引き起こします。ハードカットオーバー（旧キーが瞬時に無効化される）を強いると顧客にダウンタイムが発生します。オーバーラップを許容してください：新しいキーを作り、短い猶予期間は古いキーも併用可能にします。

基本的な質問に答えないログ

ログが役に立たない理由は大抵、サポートが必要とする「どのキーが使われたか」が含まれていないからです。有用なエントリにはキーID（シークレットではない）、タイムスタンプ、エンドポイント／アクション、環境、結果（ステータスコード付き）が含まれます。結果コードがなければ「認証エラー」か「スコープ不足」か「サーバーエラー」か判別できません。

"親切"なUXでのシークレット漏洩

作成後にシークレットを再表示しない、メールで送らない、スクリーンショットやエクスポートに含めない、同僚に共有する機能に含めないでください。失われた場合の対処は単純です：新しいキーを作ってローテーションするだけです。

リリース前の簡単チェックリスト

リリース前にサポートとセキュリティの観点から素早く点検しましょう。良いキー画面はキー作成だけでなく、安全な選択を簡単にすることが重要です。

• すべてのキーに明確な所有者と目的がある。 「誰が所有しているか、なぜ存在するか？」に答えられなければ後で苦労します。
• 「最後に誰が使ったか？」に1画面で答えられる。 各キーに最終使用時刻、環境、呼び出し元アプリ／クライアントを表示する。
• ローテーションは混雑した日でも安全にできる。 移行中は2つのキーを有効にし、簡単な計画（新キー作成→クライアント更新→トラフィック確認→旧キー無効化）を示す。
• センシティブなスコープは明示され保護されている。 高影響のスコープは平易なラベルを付け、申請に一手間かける。
• 取り消しは速く影響が測定できる。 漏洩したキーは数秒で取り消せ、ログで何が起きたか確認できる。

ノーコードツールでこれを作る場合、これらの点を「後で改善する」ではなくUI要件として扱ってください。それらがキー管理が事故を減らすか作るかを決めます。

例：アカウント全体を渡さずにパートナーへアクセスを与える

よくある状況：物流パートナーが発送用に注文データを引き取りたいが、注文を変更したり返金したり、顧客サポートメモを見たりする必要はない。ここでフルアクセスキーを渡すと被害範囲が広がります。

簡単で安全、かつパートナーにとって早いフローの例です。開発者ポータルでアカウント所有者が「Logistics Partner - Orders Read」という新しいキーを作成します。読み取り専用のスコープ orders:read のみを選び、有効期限を設定（例：90日）、現実的なら既知のIPレンジにロックすることもできます。

コピー手順は明確に：トークンは一度だけ表示され、「今コピーしてください。後でこのキーを再表示することはできません。」という明示的なテキストを出します。この一文だけで多くのサポートチケットを防げます。

数日後、パートナーが「APIがダウンしている」と報告したら、利用ログは数秒で本当の問題に答えます：

• どのエンドポイントが呼ばれ、どのキーが使われたか
• ステータスコードと返されたエラーメッセージ
• 発信元IPとUser-Agent（該当すれば）
• サポート用のタイムスタンプとリクエストID

この状況では、ログはたいてい単純なことを示します：読み取り専用キーで /orders/update を呼んでいる、あるいはリクエストが許可されていない新しいIPから来ている。サポートは推測ではなく一つの明確な修正案を返せます。

ローテーションは優れたUXが証明される場です。パートナーの担当者が退職した場合、同じ orders:read スコープの新しいキーを作成し、両方のキーを短期間有効にしておき、新しいキーで統合が確認できたら古いキーを取り消します。

成功の姿はこうです：パートナーはあなたのチームを待つことなくオンボードでき、デフォルトでアクセスは最小限に保たれ、問題が発生したときは何が起きたかを正確に見て迅速に対応できることです。

次の一歩：v1を出してから全面的に作り直すことなく改善する

小さく出しましょう。洗練されたv1は、何か月もかかって結局混乱する豪華なポータルより優れます。ほとんどのプロダクトは短いスコープリスト、基本的な利用ログ、単純で安全なローテーションフローで多くの実ニーズを満たせます。

最初は三つの構成要素から始めてください：キー、スコープ、ログ。最初はスコープを粗く（read、write、admin）保ち、必要だと証明されるまで多数の細かな権限は追加しないでください。ローテーションは退屈で良い：二つ目のキーを作り、テストし、古い方を無効化する。

有効なv1チェックリスト：

• 6〜12のスコープ以内、各スコープに何が許可されるかの明確な例
• キーごとの環境（prod vs sandbox）と明確な所有者
• 利用ログに時間、エンドポイント／アクション、ステータスコード、キーラベルを含める
• 二重有効をサポートするローテートフロー
• 誤クリックしにくい取り消しアクション

v1公開後はサポートチケットを減らす箇所に磨きをかけていきます。ログのフィルタ（日付範囲、ステータス、エンドポイント／アクション）は通常最初の勝ち目になります。次にアラート：スパイク、繰り返す認証失敗、長期間非アクティブ後の初回使用などを通知します。センシティブなスコープには「管理者承認」ではなく承認ステップを追加することも検討します。

製品内での短いヘルパーテキストはドキュメントより有効です：例えば「営業時間内にローテーションを行ってください。両方のキーを有効にしてトラフィックが切り替わったことを確認してから古いキーを無効化します。」といった一文です。

素早くセルフサーブのポータルを作りたい場合、ノーコードアプローチは次のようにモデル化できます：Keysテーブル、Scopesテーブル、Key-Scopeジョイン、Logsテーブル、管理者とサポート用のロール。AppMasterではPostgreSQL Data DesignerでDB設計を行い、Business Process Editorでローテーションや承認を実装し、管理パネルと顧客ポータルUIを柔軟にデプロイできます。