AI APIキーを安全に管理する基本

AI APIキーは、APIを呼び出すための秘密の認証情報です。漏れると、第三者が自分の環境からAPIを使い、課金、データアクセス、運用停止につながる可能性があります。安全な基本形は、キーをbrowserやmobile appへ配らず、自分のserverで保持し、必要最小の権限・利用量で実行することです。すでに公開場所へ出たキーは、ファイルから消すだけでなく失効・再発行します。

まずキーが通る経路を描く

典型的なWebアプリでは、利用者のbrowserからAI事業者へ直接APIを呼びません。次のように、serverを間に置きます。

Browser

  └─ POST /api/assistant (利用者の質問)

       └─ Application server

            ├─ 認証・権限・入力検証

            ├─ secret manager / server environmentからAPI keyを読む

            └─ AI provider APIへHTTPS request

browserに埋め込んだkeyは、開発者ツール、source map、通信内容、配布されたアプリから見つかる可能性があります。minifyや難読化は秘密の保護になりません。OpenAIもAPI keyをbrowser等のclient-side codeへ露出せず、server側でsecurely loadするよう案内しています。

置き場所とコードの最小例

ローカル開発では、OSの権限を絞った環境設定や、repoの外に置いた.envを使えます。ファイル名だけをGit除外するのではなく、実際にignoreされているか確認し、値をサンプル設定・README・ログへ書かないでください。productionではhosting providerやcloudが提供するsecret managerを優先し、誰が読み出せるかを制限します。

server側のイメージは次のとおりです。値はコードへ書かず、環境から読みます。

const apiKey = process.env.OPENAI_API_KEY;

if (!apiKey) {

  throw new Error("AI provider credential is not configured");

}

// server-only code:

// Authorization: Bearer ${apiKey}

NEXT_PUBLIC_*のようなclientへ埋め込まれる環境変数にAPI keyを置いてはいけません。API routeでは呼び出し元を認証し、userごとのrate limit、入力サイズ、許可するmodelやendpointをserver側で制御します。clientが指定したURL・model名・tool権限を無条件でそのまま転送しないでください。

キーの権限と利用範囲を分ける

API providerがproject・service account・restricted key等を提供している場合、アプリが使う機能に必要な範囲だけ許可します。支払い・管理・key作成などの権限を、通常の推論呼び出しに使うkeyへまとめません。機能ごとのpermissionが設定できないserviceでは、別projectや別organization、別credentialで影響範囲を分ける方法を検討します。

開発、staging、productionで同じkeyを共有しないことも重要です。stagingのログやデバッグツールへproduction keyが残らないようにし、環境ごとに利用量・通知・停止担当を決めます。複数人が使う場合、個人のcredentialをチャットで配らず、専用のservice identityと監査可能なsecret storageを使います。

課金と乱用を早く検知する

単にkeyを隠しても、正規利用者による誤操作やアプリのloopは起きます。provider dashboardでproject単位のusageを見られるか確認し、利用量の通知、rate limit、アプリ側のuser quotaを設定します。上限機能は、利用を止めるhard capか、通知のみかを区別してください。監視対象には急なtoken増加、短時間の連続request、予期しない地域・時間帯、利用しないmodelの呼び出しを含めます。

ログにはrequest ID、時刻、利用者IDの内部参照、model、token量、status codeなど必要最小限を残します。Authorization header、keyそのもの、顧客のprompt・responseを不用意に記録しません。障害調査に本文が必要なら、マスキングとアクセス制限を別途設計します。

GitとCIの漏えい対策

keyを一度でもrepositoryへcommitしたら、後から行を消しただけでは安全になりません。Git履歴、fork、clone、build log、CI artifactに複製された可能性があります。公開前のsecret scanningやpush protectionは予防に役立ちますが、すべての形式・秘密を検知する保証ではありません。ignore設定、review、secret scannerを組み合わせます。

CIでsecretを使うときは、workflowに明示的に渡すjobだけが読み取れる設定にします。pull request、fork、untrusted actionへproduction secretを公開しないよう、workflowの権限、依存action、environment approvalを確認します。CI logにsecretがマスクされても、変換・分割した値やdebug出力まで確実に隠せるとは限りません。

漏えいに気づいたときの対応順

1. 失効する。 provider側で該当keyをrevokeし、新しいcredentialを作る。削除作業より先に古いkeyを止めます。

2. 置き換える。 secret managerやserver environmentを更新し、影響するserviceを段階的に再起動・確認。

3. 利用履歴を見る。 発生時刻、project、endpoint、利用量、異常なrequestを確認し、課金・データ影響を調べる。

4. 複製を探す。 repo history、build artifact、CI log、issue、chat、support bundle、local backupを調査。

5. 共有先へ連絡する。 社内security窓口へ報告し、顧客・provider通知は組織のincident手順に従う。

6. 再発を防ぐ。 漏れた経路、検出の遅れ、権限過多を特定し、scannerや運用を修正。

secret値を報告書やticketへ貼り直さず、credentialの識別は末尾数文字など安全な社内手順に従います。revoke後も、利用履歴や請求を確認し、意図しない呼び出しが止まったことを確かめます。

AIものさしの判断

API key管理は、保存場所だけの問題ではありません。browserへ渡さないserver設計、最小権限、environment分離、利用量監視、rotation手順を合わせて初めて被害を小さくできます。まず1つのAPI routeでkeyがどこから読み込まれ、どのrequestに付くか確認してください。キーが既に共有・公開された疑いがある場合は、修正commitより失効を優先します。

実装前の確認項目

API routeを公開する前に、次のケースをテストします。

• 認証されていないrequestはproviderへ転送しない。

• 想定外のHTTP method、巨大な入力、許可していないmodel指定を拒否する。

• 利用者ごとのrate limitと、急増時の停止通知が働く。

• providerの401/429/5xx応答からkeyやrequest bodyをerror messageへ含めない。

• keyが未設定の環境では起動または呼び出しを安全に失敗させ、秘密値を出力しない。

• frontend bundle、source map、HTML、network responseにsecretが含まれない。

• stagingではstaging用keyのみ、productionではproduction用keyのみ使用する。

この確認は単体テストだけでは足りません。build artifactやブラウザのnetwork panelも見て、clientへ値が配信されていないことを確認します。ログは成功経路だけでなく例外経路も調べます。

secretをローテーションするとき

新しいkeyを作った後、すべてのserver instanceとbackground jobが切り替わったことを確認してから古いkeyを失効します。緊急漏えいでは、無停止切替より即時revokeが優先になる場合がありますが、その場合はAPI依存機能が停止する可能性を担当者が把握します。古い値を複数環境で共有していたなら、漏えいの疑いがなくても他環境のkeyを分離し、どのserviceが使っているか台帳に残します。再発行日、所有者、用途、失効確認者もcredential値とは別に記録します。

serverに置くだけで十分とは限らない

server-sideに置いたkeyでも、広い権限を持つ開発者、侵害されたserver、誤設定されたdebug endpointから漏れる可能性は残ります。secret managerに置く場合は、読み取り権限を実行serviceに限定し、誰が閲覧・変更したか追えるかを確認します。使い終わったkey、担当者不明のkey、期限のないkeyを定期的に棚卸しし、不要なものは失効します。