2026.08.08 プロトコル

APIキー管理とは？発行・保管・失効とローテーションの実装を解説

外部のAPIを呼ぶとき、ヘッダーに1本の文字列を載せるだけで呼び出しが通ります。この文字列がAPIキーで、発行してから使われなくなるまでの取り回しを一続きの手順として設計することをAPIキー管理と呼びます。扱う範囲は、生成方法と保存形式、キー単位で権限と流量を絞る当て方、無停止で入れ替えるローテーション、漏えいを拾ってから失効させるまでの手順、そして環境変数のままでよい条件までです。認証情報以外の脅威まで含めた全体像はOWASP API Top 10に沿った対策に譲り、ここでは鍵そのものの扱いだけに絞ります。

まとめ｜先に決める4項目とAPIキーを使い続けられる境界

設計の入口で決めるのは4つです。生成は暗号論的乱数で128ビット以上のエントロピーを持たせ、保存はハッシュ値と検索用識別子の2列に分けて平文を持たない。制限はスコープ・呼び出し元・流量の3層で、キー1本あたりの影響範囲を最初から狭めておく。失効はキー単位で即座に効き、再発行の窓口が業務手順として決まっている。この4つが揃っていれば、漏えいしても被害は1本のキーが持つ権限の内側で止まります。

APIキーのまま運用してよいのは、サーバ間の通信であること、鍵の配布先が契約で把握できる範囲に閉じていること、キー1本が持つ権限で事故が起きても影響が自社内に収まること。この3条件が揃う場面です。ユーザーの代理として動く、第三者へ広く配布する、監査で認証情報の有効期限を求められる。どれか1つでも当てはまったら、OAuth 2.0やmTLSへ切り替える設計に移します。移行はキーを残したまま新方式を並走させ、旧キーの利用が閾値を下回った時点で期限を切って畳むのが安全です。

APIキー管理とは｜発行から失効までのライフサイクルを設計する

APIキーが担う範囲｜認証と識別は担えても認可は別に設計する

APIキーは「この呼び出しは誰からか」を示す識別子であり、同時に「その主張が正しいか」を示す認証情報でもあります。1本の文字列が両方を兼ねる点が、扱いやすさと危うさの双方の理由でしょう。持っている者が本人とみなされるため、盗まれた瞬間に成り代わりが成立します。

一方で、何をしてよいかという認可はキー自体には書かれていません。サーバ側でキーに紐づけたスコープを引いて判定する設計が要ります。ここを省いて「キーが有効なら全操作を許す」と作ると、読み取り専用の連携先へ渡した1本が、削除まで通る鍵になります。識別・認証・認可は別々の層として実装してください。

ライフサイクルの4工程｜発行・保管・利用制限・失効の切り分け

管理を工程に分解すると4つになります。発行（誰の依頼でどの権限のキーを作るか）、保管（サーバ側とクライアント側でどう持つか）、利用制限（何を呼べて何回まで許すか）、失効（いつ止め、いつ入れ替えるか）。漏れやすいのは失効で、発行の画面はあっても停止の導線がない実装が珍しくありません。

4工程は担当が散らばりやすく、責任の谷間が生まれます。APIマネジメント基盤の構成要素を整理する段階で、受け持ちを1枚に書き出しておくと後戻りが減るでしょう。

他方式との位置づけ｜Bearerトークンやセッションとの違い

APIキーは基本的に長命で、明示的に失効させるまで有効です。対してアクセストークンは発行時に有効期限を持ち、期限が来れば自動的に使えなくなります。セッションIDはブラウザの利用者に紐づき、ログアウトやタイムアウトで消えます。

この差が設計判断を分けます。長命であることは、CIから深夜バッチまで人の介在なく動かせる利点であり、同時に漏えいに気づかない限り攻撃者が使い続けられる欠点でもあるでしょう。だからこそ期限の代わりに、監視とローテーションという運用側の仕組みで寿命を人為的に区切ります。

鍵の生成と保管｜ハッシュ化して照合する実装とプレフィックス設計

鍵の生成｜暗号論的乱数で128ビット以上のエントロピーを確保

連番やUUIDv1のような推測可能な値、一般的な疑似乱数からキーを作ってはいけません。言語標準の暗号論的乱数（Pythonなら secrets、Node.jsなら crypto.randomBytes、Goなら crypto/rand）を使い、32バイト前後をURL安全な文字列へ符号化します。

import secrets, hashlib

raw    = "sk_live_" + secrets.token_urlsafe(32)   # 利用者へ一度だけ見せる値
lookup = raw[:16]                                  # 検索用の識別子（平文で保存）
digest = hashlib.sha256(raw.encode()).hexdigest()  # 照合用のハッシュ値

ハッシュにはSHA-256のような高速な関数を使って構いません。利用者パスワードと違い、キー自体が十分な長さの乱数なら総当たりは現実的でないためです。毎リクエストで検証する以上、遅い関数はレイテンシへ直接効きます。

保存形式｜平文を持たずハッシュ値と識別子の2列に分けて照合する

データベースにキーそのものを保存すると、ダンプが1度流出しただけで全顧客の鍵が漏れます。ハッシュだけを持てば安全ですが、今度は「このキーはどのレコードか」を引けません。ハッシュ値は前方一致検索ができないためです。

解法は列を2つに分けることです。先頭16文字程度を lookup として平文で保存してインデックスを張り、全体のSHA-256を digest として保存します。検証時は lookup で1行に絞り込んでから、digest を定数時間比較で突き合わせます。

SELECT id, scopes, revoked_at, expires_at
  FROM api_keys
 WHERE lookup = ?
   AND revoked_at IS NULL

照合はアプリ側で hmac.compare_digest のようなタイミング差の出ない比較を使ってください。取り出した行に対して文字列の等値比較を素朴に書くと、一致した先頭バイト数が応答時間の差として観測される余地が残ります。

プレフィックス設計｜用途と環境を鍵の先頭で読み取れるようにする

キーの先頭に固定の接頭辞を置くと、運用の見通しが一段よくなります。sk_live_ と sk_test_ のように本番と検証を書き分けておけば、検証用の値を本番へ貼り違えた事故を検知できます。読み取り専用と書き込み可を接頭辞で分ける設計も取り回しがよいでしょう。

接頭辞にはもう1つ効果があります。GitHub公式のシークレットスキャンは認証情報の型ごとに検出パターンを持つため、特徴のある接頭辞は機械的に見つけやすくなるでしょう。ランダム文字列だけのキーは他と区別がつかず、検知の網から漏れます。

配布と初回表示｜生成直後に一度だけ見せる画面と再発行の導線設計

平文を保存しない設計を選んだ以上、キーの全体を見せられるのは生成直後の1回だけです。画面には全体をコピーできるボタンと、閉じると再表示できない旨の明示を置き、二度目以降の一覧では sk_live_9f3a… のように先頭数文字だけを出します。

スコープ設計｜キー単位で権限とレート上限を絞り込む実装の手順

スコープ｜読み取りと書き込みを別キーに割り当てる粒度の決め方

粒度は細かすぎても粗すぎても運用が壊れます。実務で扱いやすいのは、リソース種別と操作種別の組を invoices:read invoices:write のような文字列で表し、キーに複数持たせる方式です。判定はミドルウェアで一度だけ行います。

Google Cloud公式のAPIキーに関する案内でも、制限を加えることで不正使用時の影響を軽減できる点と、チームメンバーごとに独立したキーを割り当てる点が挙げられています（2026年8月時点）。共有された1本を全員で使う運用は、失効させた瞬間に全員が止まるため、事故対応そのものを躊躇させます。

呼び出し元の制限｜IP範囲・参照元・許可APIの3層で絞り込む

スコープに加えて、呼び出し元の条件でも絞れます。サーバ間連携なら送信元IPアドレスの範囲を許可リストに入れ、範囲外からの提示は鍵が正しくても拒否してください。ブラウザから直接呼ぶキーなら参照元の制限を、モバイルアプリならアプリ署名の制限を当てます。

レート制限との連動｜キー単位のクォータで乱用と請求増を抑える

流量の上限はキー単位で持たせます。全体で毎秒何回という基準だけだと、1本の暴走が他の利用者を巻き込むでしょう。キーごとに1分あたりの上限と1日あたりのクォータを別々に持たせ、超過時は429で返し、Retry-After を添えます。

強制する場所は、アプリ本体よりも手前が扱いやすくなります。APIゲートウェイの役割と導入判断で整理したとおり、キーの検証とクォータの適用を入口へ寄せると、各サービスの実装から共通処理が消えるでしょう。ただし失効の反映に遅延が生じる構成では、キャッシュの寿命を秒単位まで詰めます。

ローテーション｜無停止で鍵を切り替える二重鍵運用と失効の手順

二重鍵での切り替え｜新旧を並走させて呼び出し元を移行させる流れ

1本のキーを差し替える操作を「無効化してから新規発行」の順で行うと、その間の呼び出しはすべて失敗します。正しい順序は、新しいキーを追加発行して両方を有効にし、呼び出し元の設定を新しい値へ書き換え、旧キーの利用が0になったことをログで確認してから旧キーを失効させる、の4段です。

AWS Secrets Manager公式のローテーション関数は、この考え方を4つのステップとして持っています（2026年8月時点）。create_secret が新しい値を AWSPENDING というステージングラベルで保存し、set_secret が対象側の認証情報を新しい値へ合わせ、test_secret が新版で実際に接続して読み取りを確認し、finish_secret が AWSCURRENT を新版へ移します。このとき同じAPI呼び出しで AWSPENDING が外れ、旧版には AWSPREVIOUS が自動で付きます。

勘所は2つあります。新しい値を先に保存してから対象側へ反映する順序が、途中で失敗しても同じ値を再利用できる冪等性を生むこと。直前の正常な値が AWSPREVIOUS として残り、切り替え直後の不具合でも戻せること。自前で実装する場合も、この2点は模倣してください。

ローテーション周期｜期限起点と事故起点の2つのトリガーを持つ

周期は2系統で考えます。1つ目は時間起点で、90日ごとのように予定された入れ替えです。漏えいに気づかない状態が続く期間の上限を、こちら側で決める行為にあたります。2つ目は事故起点で、退職・委託先の変更・スキャン検知を合図に即時入れ替えます。

OWASPのシークレット管理に関する記述では、ローテーションの定期実施と自動化を推奨する一方、利用者本人の認証情報についてはNIST推奨に沿い漏えい疑いがある場合に限るとしています。機械が持つ認証情報と人が持つ認証情報で扱いが分かれる点は、社内規程を書くときに混ざりやすいので分けて記述してください。

自動化の範囲｜発行と反映を人手に残さず配布系まで一気通貫にする

手作業のローテーションは、回数を重ねるほど飛ばされます。自動化の範囲は「新しい値の生成」だけでは足りず、呼び出し元の設定へ反映するところまで含めて初めて回り始めるでしょう。コンテナならデプロイ時にシークレットストアから取得し、CIならジョブ開始時に短命の値を発行します。

Secrets Managerのローテーションには、Lambda関数を使う方式のほかに、サービス側が構成まで受け持つ managed rotation と、パートナー保有のシークレットを対象とする方式があります（2026年8月時点）。いずれかのステップが失敗した場合はローテーションウィンドウ内で全体を複数回リトライする仕様のため、関数側は途中失敗を前提に何度呼ばれても同じ結果になるよう書きます。

漏えい検知と事故対応｜検出から失効・再発行までの手順を決める

検知の仕組み｜リポジトリとログを対象にした走査の当て先を決める

もっとも多い流出経路はソースコードです。GitHub公式によれば、パブリックリポジトリではシークレットスキャンが無料で自動実行され、対象はGit履歴だけでなくIssue・プルリクエスト・Discussion・Wiki・Gistの説明やコメントにも及びます（2026年8月時点）。新しい認証情報タイプが追加された際には定期的な再スキャンも行われます。

パートナーの認証情報が検出されると発行元へ通知が渡り、発行元側が失効などの措置を取れる仕組みも用意されています。これは利用者側の認証情報の有効性を確かめる validity check とは別の経路です。自社がAPIを提供する側なら、登録しておくと自力で気づく前に止められます。

漏えい時の手順｜失効・再発行・履歴消去・影響調査の順で進める

順序を先に決めておかないと、担当者は「まず消そう」としてコミット履歴の書き換えから手を付けます。OWASPの記述では、即時取消・自動化プロセスによる置換・コードとログからの完全削除という順で示されています。まず止め、次に代替を用意し、最後に痕跡を消すという並びです。

4つ目として影響調査を足します。漏えいしたキーが有効だった期間の呼び出しログを洗い、書き込みの有無と送信元の偏りを確認します。ここで見るべき項目が揃っているかが、次の節の監査ログ設計に跳ね返るでしょう。

監査ログの設計｜誰がいつ発行し何に使ったかを追える項目を残す

OWASPが挙げる記録項目は、要求者・承認または却下の結果・使用時刻・有効期限切れ・認可エラー・更新履歴です。加えて、ログ自体が改ざんや削除の試みに耐えることを求めています。アプリケーションと同じデータベースへ書くだけでは、侵入時に同時に消されます。発行・失効・スコープ変更といった管理操作は、追記のみのストアへ分けて書き出してください。

保管先の選び分け｜環境変数とシークレット管理サービスの判断基準

環境変数で足りる条件｜単一環境・少数キー・入れ替え頻度が低い

環境変数は「劣った選択肢」ではありません。稼働環境が1系統に収まっている、扱うキーが数本にとどまる、入れ替えが年に数回で手作業でも回る。この3条件がそろうなら据え置いて構いません。この規模で専用サービスを足しても、依存が1つ増えるだけです。

ただし、条件を満たす場合でも守るべき線が2つあります。値を含むファイルをリポジトリへ入れないこと、プロセスの外へ出さないこと。.env を .gitignore へ入れるだけでなく、コンテナイメージへ焼き込まない、デバッグ画面で環境変数一覧を出さない、といった運用まで含みます。

専用サービスの採用線｜自動更新と細かな権限制御が必要になる場面

環境変数から移る判断は、次のどれかが立った時点です。環境が本番・検証・開発と増えて値の突き合わせが人手で追えなくなった、ローテーションを自動で回したい、誰がどのキーを読めるかをキー単位で制御したい、読み出しの監査ログを残す必要が出た。

移り先は、AWS Secrets Manager・Azure Key Vault・Google Secret Managerのようなクラウド事業者の提供する仕組みと、HashiCorp Vaultのような独立した基盤に分かれます。OWASPは管理基盤を標準化して中央へ寄せることを勧めており、環境ごとに別の仕組みを使う構成は避けたほうが無難でしょう。起動時にセッション単位の短命な値を取得する動的シークレットの考え方も示されています。

保管先の比較表｜取り回し・監査・運用コストを一覧で並べて見る

保管先 向く規模 自動更新 読み出し監査
環境変数 単一環境・数本 手作業 残らない
クラウドの管理サービス 同一事業者で完結 組み込みで対応 基盤側に残る
独立したシークレット基盤 複数環境にまたがる 動的発行に対応 基盤側に残る
CIの秘密変数 ビルド時のみ利用 手作業が中心 実行ログに残る

どの行を選んでも、呼び出し側の実装は「起動時に1回読んでメモリに持つ」形へ寄せておくと入れ替えが効きます。リクエストのたびに取得しにいく作りでは、保管先の障害がそのままAPI連携の障害になるでしょう。呼び出す側の組み立て方はREST・認証・エラー処理までの実装手順にまとめてあります。

APIキーで足りる境界｜OAuth 2.0やmTLSへ切り替える条件

APIキーのままでよい3条件｜サーバ間・限定公開・影響が閉じる

次の3つが同時に成り立つなら、APIキーで押し通して構いません。第一に、通信がサーバ間に閉じていること。ブラウザやモバイルアプリの内部に置く構成は、取り出される前提で考えます。第二に、配布先が契約で把握できる範囲にとどまること。第三に、キー1本の権限で事故が起きても影響が取引先の内側に収まること。

切り替えを促す兆候｜ユーザー代理・第三者配布・監査要件の追加

3つの兆候が判断の合図になります。1つ目は、APIが「誰かの代わりに」データへ触り始めたとき。エンドユーザーの同意に基づく委任が要るため、OAuth 2.0の枠組みへ移します。2つ目は、不特定多数の開発者へ配布し始めたとき。発行・失効・スコープ変更を利用者自身に任せる管理画面が要ります。

3つ目は、監査で認証情報の有効期限や相互認証が求められたとき。取引先の情報セキュリティ基準で「証明書による相互認証」を条件にされる場面が該当し、mTLSへの移行が現実的な回答になります。いずれの兆候も、機能追加ではなく責任分界の変化として現れます。

移行の進め方｜キーを残したまま新方式を並走させ期限で畳む手順

切り替えは一斉には行いません。新方式のエンドポイントを別系統で立ち上げ、既存のキーはそのまま生かします。呼び出し元ごとに移行を進め、旧方式の呼び出し数を週次で見ながら、閾値を下回った時点で終了期日を通知します。

畳む基準は件数だけでなく、残った呼び出し元の性質でも判断します。残り1社が基幹連携なら件数が少なくても個別調整が要り、検証用スクリプトばかりなら期日を切って止めて構いません。終了の告知から実際の停止まで、最低でも2つの請求サイクルを挟むと連絡の行き違いを吸収できるでしょう。

受託開発での引き渡し設計｜鍵の所有者と確認項目を契約前に決める

設計レビューで見る項目｜保存形式・スコープ・失効経路と監査ログ

レビューでは4点だけ機械的に確認します。データベースにキーの平文が入っていないか。1本のキーが呼べる範囲が発行時に絞られているか。管理画面から即座に失効でき、その効果がキャッシュ越しでも数秒以内に効くか。誰がいつ発行し失効させたかが追記のみのログに残るか。

引き渡し時の取り決め｜鍵の所有者と再発行の窓口を契約前に決める

技術以外で揉めるのが所有と窓口です。本番の鍵を誰が保持するのか、開発ベンダーが本番の値を見られる状態のままでよいのか、事故時に誰が失効ボタンを押すのか。保守契約に「認証情報の入れ替え作業」が含まれるかも、着手前に文言として確定させます。

実務では、本番の鍵は発注者側が保持し、開発側は検証用の鍵のみを扱う形へ寄せると責任が明確になるでしょう。移行日にだけ本番へ触れる必要があるなら、期間限定のキーを発行し、作業完了と同時に失効させる段取りを組みます。API連携の設計から実装、引き渡し後の運用設計までの相談はAPI開発・システム連携で受け付けています。

よくある質問

APIキーとアクセストークンの違いは何ですか？

寿命と発行の経路が違います。APIキーは管理画面で作られ、失効させるまで有効な長命の値です。アクセストークンは認可サーバが発行し、多くは分単位から時間単位の有効期限を持ち、リフレッシュの仕組みで更新されます。無人のバッチやサーバ間連携ならキーが扱いやすく、利用者の同意に基づく委任が絡むならトークンの枠組みへ寄せる、という切り分けになります。

APIキーはURLのクエリパラメータに付けてよいですか？

避けてください。クエリ文字列はアクセスログ・プロキシ・ブラウザ履歴・リファラーヘッダーへ残り、意図しない場所に写ります。Google Cloud公式の案内でも、キーは専用ヘッダーやクライアントライブラリ経由で渡し、クエリパラメータでの送出は避けるよう示されています（2026年8月時点）。既存APIはヘッダー方式へ移し、旧方式に終了期日を設けてください。

ローテーションの周期は何日にすべきですか？

公的な規定として日数が定められているわけではありません。Google Cloud公式の案内にも日数の記載はなく、定期的な新規作成と古いキーの削除という表現にとどまります。実務では30日・60日・90日から選ぶ例が多く、自動化できているなら短く寄せます。日数そのものより、事故起点の即時入れ替えが動くかを先に整えてください。

ハッシュ保存にすると前方一致検索ができなくなりませんか？

そのとおりなので、列を分けて解きます。キーの先頭16文字程度を検索用の識別子として平文で保存しインデックスを張り、キー全体のハッシュ値は別列に持ちます。検証は識別子で1行に絞ってからハッシュを定数時間比較で突き合わせる2段構えです。識別子だけでは認証は成立しないため、平文で持っても認証情報の漏えいにはあたりません。

GitHubに上げてしまったキーは削除すれば戻せますか？

コミットを消しても、そのキーは漏えいしたものとして扱ってください。フォークやキャッシュ、クローン済みの手元リポジトリに残る可能性があり、履歴の書き換えでは回収しきれません。順序は、まず失効、次に新しいキーの発行と反映、最後に履歴とログからの削除です。あわせて有効だった期間の呼び出しログを洗い、想定外の操作がなかったかを確認します。

関連記事

資料請求

RELATED POSTS 関連記事

一覧へ戻る