前回、API の認証方式を6つ並べたときに、いちばん手軽で、いちばん扱いに気をつけたいのが API キーだと感じました。発行するのは画面のボタン1つですが、そのあと「どこに置くか」「いつ入れ替えるか」「漏れたらどうするか」まで決めておかないと、長く使われる秘密が増えていきます。この記事では、API キーのしくみと一生（発行から取り消しまで）を、Microsoft・Cisco Meraki・GitHub・OWASP のドキュメントで確かめながら図にしました。
- API キーとは何か。パスワードやトークンとの違い
- キーの送り方と、API 側での確かめ方
- キーは「誰のもの」か（管理者・サブスクリプション・リソース）
- 保管・2つのキーでの入れ替え・取り消しと、漏れに気づくしくみ
- API キーで済ませてよい場面と、避けたい場面
API キーとは
API キーは、サービスが発行するランダムな文字列で、API を呼ぶたびにリクエストに付けて送ります。API の側は、受け取ったキーを自分の台帳で引いて、「誰のキーか」「何をしてよいか」を判断します。キーの文字列そのものに意味はなく、台帳とつながって初めて意味を持ちます。
| 項目 | パスワード | API キー | アクセストークン |
|---|---|---|---|
| 誰が作るか | 利用者が決める | サービスが作る | 発行元がサインインのあとに作る |
| 使うもの | 人のサインイン | プログラムからの呼び出し | プログラムからの呼び出し |
| 期限 | 変えるまで | 取り消すまでのことが多い | 短い（1時間前後など） |
| 漏れたとき | 変えるまで使われる | 取り消すまで使われる | 期限が来れば使えなくなる |
トークンとの違いは、セッションとトークンの記事やAPI の認証方式の記事でも比べています。
送り方と、API 側の確かめ方
API キーが発行されてから使われるまでを、やり取りの順に並べると次のようになります。
キーを入れる場所は、サービスごとに決まっています。
| サービス | キーを入れる場所 |
|---|---|
| Azure の AI サービス（Translator など） | Ocp-Apim-Subscription-Key ヘッダ |
| Azure API Management で公開した API | Ocp-Apim-Subscription-Key ヘッダ（名前は API ごとに変えられる） |
| Cisco Meraki Dashboard API | Authorization: Bearer の形 |
例：Translator にキーを付けて送る（Microsoft のドキュメントの例）
curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp
API Management の場合、受け取ったキーが有効なサブスクリプションのものかを確かめ、そのサブスクリプションの範囲に入る API なら通します。キーが無効なら、401（Access denied）で断ります。
API Management はクエリ文字列（subscription-key）でもキーを受け取れますが、URL はログや履歴に残りやすいので、OWASP はパスワードやトークン、API キーを URL に入れないよう求めています。また、API Management は受け取ったキーを、既定ではそのままバックエンドにも渡します。バックエンドのログに残したくなければ、ポリシーでヘッダを外します。
キーは「誰のもの」か
API キーの権限は、そのキーが結び付いている「持ち主」の権限です。持ち主の種類は、サービスによって大きく3つに分かれます。
| 型 | この型に共通すること | 例のサービスでの決まり |
|---|---|---|
| 管理者に結び付く | キーは、発行した管理者と同じ権限を持つ | Meraki Dashboard API の場合：1人が同時に持てる有効なキーは2本まで。期限はなく、取り消すまで有効 |
| サブスクリプションに結び付く | キーは、契約（サブスクリプション）で決めた範囲の API に使える | Azure API Management の場合：範囲を製品・1つの API・全 API から選べる。回数の上限（クォータ、レート制限）をサブスクリプションごとにかけられる。全 API に使える組み込みのサブスクリプションのキーは、アプリに入れない |
| リソースに結び付く | キーは、そのリソースへのアクセスを表す。誰が使っても同じ権限になる | Azure の AI サービスの場合：リソースごとに KEY1 と KEY2 の2本がある。Azure AI Search の場合：管理キーは読み書きすべてができる |
キーの本数や期限、範囲の決め方はサービスごとに違います。表の右の列は、例に挙げたサービスでの決まりです。
「人ごとに権限を分けたい」「誰が呼んだかを残したい」という要件には、リソースに結び付くキーは向きません。Microsoft のドキュメントでも、AI サービスのキーは手軽に始められる一方で、Azure の役割ベースのアクセス制御（RBAC）が必要な場面には足りない、と説明しています。
キーの一生：発行から取り消しまで
API キーは、作ったあとの扱いで安全さが決まります。
保管：コードに書かない
Microsoft のドキュメントは、API キーをコードに直接書かず、公開もしないこと、使う場合は Azure Key Vault に置き、定期的に入れ替え、Key Vault への接続は役割と通信の制限で絞るよう求めています。OWASP も、シークレットには必要最小限の権限だけを与えるよう勧めています。
それでも、うっかりコードに入れてしまうことはあります。GitHub には、これに気づくしくみがあります。
| しくみ | 何をするか |
|---|---|
| シークレットスキャン | リポジトリのすべてのブランチの履歴から、書き込まれた資格情報を見つける。対応するサービスのキーが見つかると、そのサービスに知らせ、サービス側でキーを取り消すなどの対応ができる |
| プッシュ保護 | シークレットを含むプッシュを、リポジトリに届く前に止める。止めたのを押し切った場合は、アラートが作られる |
入れ替え：2つのキーで止めずに替える
多くの Azure のサービスは、キーを2本ずつ用意しています。キーを作り直すと古い値はすぐ使えなくなるので、2本を交互に使うことで、サービスを止めずに入れ替えられます。
| 手順 | やること（Azure の AI サービスの手順） |
|---|---|
| ① | 両方のキーを使っているなら、アプリをキー1だけに寄せる |
| ② | 使っていないキー2を作り直す（ポータルの Keys and Endpoint で Regenerate Key 2） |
| ③ | アプリを新しいキー2に切り替える。ログなどで、全員が切り替わったことを確かめる |
| ④ | キー1を作り直す。次の入れ替えでは、キー1とキー2の役割を逆にする |
Azure API Management は、サブスクリプションキーに期限を付けたり、自動で入れ替えたりする機能を持っていないと、ドキュメントで明記しています。定期的な入れ替えは、PowerShell や SDK で自分たちの手順として自動化します。期限付きのアクセスが必要なら、トークンのように期限を持つしくみを使います。Azure AI Search のドキュメントでも、2本の管理キーを同時に作り直すと、キーを使うリクエストはすべて 403 になると注意しています。
取り消し：漏れたらすぐ
OWASP は、漏れたキーはすぐに取り消すよう求めています。サービスごとの止め方は次のとおりです。
| サービス | 止め方 |
|---|---|
| Azure の AI サービス | 漏れたキーを作り直す（古い値はすぐ使えなくなる） |
| Azure API Management | サブスクリプションを一時停止・キャンセル・削除する、またはキーを作り直す |
| Meraki Dashboard API | API キーの画面（Organization ›› API & Webhooks ›› API keys and access）で取り消す |
取り消したあとは、そのキーで何が呼ばれたかをログで確かめ、新しいキーをアプリに配り直します。
API キーで済ませてよい場面・避けたい場面
OWASP は、API キーはサービス妨害の影響を減らすのに役立つ一方、第三者に配ると漏れやすいので、重要なリソースを API キーだけで守らないよう勧めています。
| 向いている場面 | 避けたい場面 |
|---|---|
| どのアプリ（契約）からの呼び出しかを見分け、回数の上限をかけたい | 人ごとに権限を分けたい、誰が操作したかを残したい |
| 製品やサービスの API を、まず手軽に試したい | 重要なデータや設定を、キーだけで守る |
| 相手のサービスがキーにしか対応していない | Azure の中で動くプログラムから Azure のサービスを呼ぶ |
Azure の中で動くプログラムなら、Microsoft はキーではなく、Microsoft Entra ID とマネージド ID で認証することを勧めています。Entra ID に移したあとは、リソースの disableLocalAuth を有効にしてキーでの認証を止められます。Azure AI サービスでは、Azure Policy でサブスクリプション全体に強制することもできます。
企業での例
| 場面 | キーの型 | 運用のポイント |
|---|---|---|
| 取引先に、API Management で自社の API を公開する | サブスクリプション | 取引先ごとにサブスクリプションを分け、範囲と回数の上限をかける。漏れたらその取引先のサブスクリプションだけを止める |
| 社内アプリから Azure の AI サービス（Translator、Azure OpenAI など）を呼ぶ | リソース | まずキーで試し、本番はマネージド ID と Entra ID に移してキーを無効にする |
| 運用の自動化ツールで Meraki の設定を取得・変更する | 管理者 | 自動化専用の管理者を作り、必要な権限だけを与えてからキーを発行する |
| 社内の検索アプリから Azure AI Search を呼ぶ | リソース | 検索だけのアプリには、読み書きできる管理キーを渡さない。役割（RBAC）への移行も検討する |
まとめ
| 項目 | ポイント |
|---|---|
| API キー | サービスが作るランダムな文字列。API 側の台帳で持ち主と権限を引く |
| 送り方 | サービスごとに決まったヘッダ。URL に入れない |
| 持ち主 | 管理者・サブスクリプション・リソースの3つの型。キーの権限は持ち主の権限 |
| 保管 | コードに書かず Key Vault へ。GitHub のシークレットスキャンとプッシュ保護で漏れに気づく |
| 入れ替え | 2本のキーを交互に作り直す。自動では入れ替わらない |
| 取り消し | 漏れたらすぐ。サービスごとの止め方を決めておく |
| 使いどころ | アプリの見分けと回数制限には便利。重要なものはキーだけで守らない |
参考にした資料
この記事は、次の公式ドキュメントと資料で内容を確かめて書きました。仕様や対応状況は変わることがあるので、最新の情報はリンク先で確かめてください。
- REST Security Cheat Sheet・Secrets Management Cheat Sheet（OWASP）：API キーだけに頼らないこと、URL に入れないこと、最小限の権限、入れ替え、漏れたらすぐ取り消すこと
- Authenticate requests to Foundry Tools（Microsoft Learn）：Ocp-Apim-Subscription-Key、KEY1 と KEY2、キーでは RBAC に足りないこと、Translator の例
- Rotate API keys（Microsoft Learn）：2つのキーでの入れ替えの手順、作り直した古い値はすぐ使えなくなること
- Disable local authentication in Foundry Tools（Microsoft Learn）：disableLocalAuth と Azure Policy
- Quickstart: Get started using chat completions with Azure OpenAI（Microsoft Learn）：キーをコードに書かない、Key Vault に置く、マネージド ID を勧めること
- Subscriptions in Azure API Management（Microsoft Learn）：サブスクリプションの範囲、全 API 用のサブスクリプション、キーの確かめ方と 401、期限や自動入れ替えの機能がないこと、一時停止・キャンセル
- Connect to Azure AI Search using keys（Microsoft Learn）：管理キーの入れ替え、両方を作り直すと 403 になること
- Authentication – Meraki Dashboard API v1（Cisco Meraki Developer Hub）：キーの権限、1人2本まで、取り消すまで有効、発行と取り消しの画面
- Secret scanning・Push protection（GitHub Docs）：履歴からの検出、サービスへの通知、プッシュを止めるしくみ
あとがき
調べてみて意外だったのは、API Management のように API キーを中心にしたサービスでも、キーの期限や自動の入れ替えは「自分たちで作るもの」とはっきり書かれていたことです。発行するときに、入れ替えの手順と止め方までセットで決めておく。これだけで、キーはずっと扱いやすくなると感じました。キーの権限は持ち主の権限そのものなので、「誰のキーとして発行するか」を最初に考えるのも大事なところです。
コメント