複数アプリのAPIキーをまとめて管理する方法

APIキーを1つ差し替えるたびに、アプリのフォルダを1つずつ開いて.envを直していました。どのアプリがそのキーを使っているかは覚えておくしかなく、直し忘れた所はあとで止まって初めて気づきます。本番側の更新を忘れたときは、AIの呼び出しが有料のサービスに切り替わり、請求だけが増えました。

そこで、キーの元を1か所にまとめ、確認と書き換えを自作の管理ツールの操作にまとめました。この記事はその実録です。配布しているサービスではなく、私のPCで動かしている自作ツールの話です。

自作ツールでできること

元の値はkeys.envという1つのファイルにだけ書き、アクセス権を自分だけに絞ったフォルダに置いています。各アプリの.envは、そこから配った写しです。

ツールはメニューから選ぶ形にしています。

  1  点検     キーが生きているか / モデルが実在するか
  2  棚卸し   .env を集めて控えを取り、台帳を作り直す
  3  配布     keys.env の値を各プロジェクトの .env へ(差分表示のみ)
  4  配布(適用)  上の差分を実際に書き込む
  5  試験     実際に1回だけ生成して動作確認

アプリを開いて回っていた作業は、ほぼこの中の3つに置き換わりました。

前にやっていたこと	今の操作
どのアプリにどのキーがあるか、フォルダを開いて探す	棚卸し
各アプリの.envを開いて値を書き換える	配布（差分を見てから適用）
キーが生きているか、設定が漏れていないかを見て回る	点検

キーを交換するときの流れ

1. 元を直す。 keys.envの該当行だけを新しい値にします
2. 差分を見る。 メニューの3です。この時点では何も書き換えません
3. 適用する。 差分が想定どおりなら4を押します
4. 本番を別に直す。 GitHub Secretsのような本番の登録は、このツールからは届きません。別の操作で更新します
5. 確かめる。 点検を1回回し、本番の実行も1回見ます

差分の表示は、値を伏せ字にして、どのアプリのどのファイルの、どの名前が変わるかだけを出します（下は形を示すためのダミーです）。

  blog / .env.local
    [変更] OPENAI_API_KEY: abcdef…1234 → abcdef…5678
  shop / .env.local  (新規作成)
    [追加] STRIPE_SECRET_KEY: (未設定) → wxyz12…9999

上の 2件は、まだ書き込んでいません。

元に値が無い名前は「欠落」と出て、そのアプリには書きません。空のまま配ると、そのアプリが黙って壊れるからです。

適用は、既存の.envの対象の行だけを書き換えます。ほかの行やコメントには触らず、まだ無い名前は末尾に足します。書き換える前には、日時を付けた控えを同じ場所に残します。値が変わらないファイルは控えも作りません。配るたびに控えが増えるのを避けるためです。

考え方だけを抜き出すと、次の形です。

# 概念例: 既存の .env のうち、配る名前の行だけを差し替える
import re

def update_env(text: str, targets: dict[str, str]) -> str:
    out, written = [], set()
    for line in text.splitlines():
        m = re.match(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=", line)
        if m and m.group(1) in targets:
            out.append(f"{m.group(1)}={targets[m.group(1)]}")
            written.add(m.group(1))
        else:
            out.append(line)  # 配らない行はそのまま残す
    out += [f"{n}={v}" for n, v in targets.items() if n not in written]
    return "\n".join(out) + "\n"

試すときは、先に控えを取った.envで動かしてください。実物は、これに差分の表示・控え・アプリごとに配る名前の絞り込みが付いています。

アプリごとに配るのは、そのアプリが使う名前だけです。全部を配ると、1つのアプリから全部のキーが漏れるからです。

台帳と、値の食い違いの見つけ方

棚卸しは、全プロジェクトの.env系のファイルを探して控えを取り、台帳を2つ作り直します。

• キー一覧: 変数名、伏せ字の値、点検の結果、そのキーが書かれているアプリ
• プロジェクト台帳: アプリごとに、呼んでいるAI、動く場所、.envのファイル、配っているキーの本数

キーを替えるとき、どのアプリに影響するかは台帳を見れば分かります。記憶やフォルダの検索に頼らなくて済むようになったのが、いちばん大きい変化でした。AI以外のキー（決済やデータベースなど）も、名前と書かれているアプリだけは台帳に出ます。

もう1つ、棚卸しは同じ変数名なのに値が違う場所を一覧にします。

! 同じ変数名で値が違う箇所が 1件あります:
    OPENAI_API_KEY
      blog / .env.local → abcdef…1234
      shop / .env.local → abcdef…0000

片方だけ古いキーのまま、という更新漏れの候補がここに出ます。どちらが正しいかはツールが決めず、人が決めて元を直します。開発用と本番用で値を分ける設定にした名前は、違っていて正しいので一覧から外します。

まとめて点検する

点検は、次の3種類をまとめて見ます。

• キー: AIのキーが実際に認証を通るか。各社のモデル一覧を取りにいって判定します。決済などAI以外のキーは見ていません
• モデル: 設定ファイルに書いたモデル名を集めて、各社のモデル一覧と照合します。一覧に無いものに印を付けます。廃止や名前のずれに気づくためのもので、一覧に出ない別名もあるので、印が付いたら必ず使えない、という意味ではありません
• 誤コミット対策: 各リポジトリに、秘密の誤コミットを止めるpre-commitが入っているか。.envが.gitignoreで本当に外れているか（git check-ignoreで実際に判定）。コードが読んでいるのに元のファイルに無いキーの名前

最後の1つは、本番の登録にだけ値があるキーを見つけるためです。元に無いと、作り直しや引っ越しのときに誰も値を持っていない、という状態になります。ただし、コードの書き方によっては拾えない読み方もあります。

pre-commitは、ステージにある.env系のファイルや、決まった形のキーの文字列を見つけるとコミットを止めます。止めたときは中身を出さず、ファイル名と行番号だけを出します。本物のキーの形をした行は、例外の印を付けても止まる作りにしました。

AIの呼び出しもまとめている

同じツールに、AIを呼ぶ共通の窓口も入れています。無料枠のキーから順に使い、尽きたら課金のキーへ落ちる順番と、課金の呼び出し回数の上限を1か所で決めています。アプリ側はキーの本数を知らなくて済みます。

ただし数えているのはこのPCから呼んだ分だけで、GitHub Actionsのような外で動く分は入りません。使うのを止める判断は、回数ではなく実際に返ってきた「上限です」の応答で行っています。

まだできないこと

• 本番への反映は別の操作です。 配布で揃うのは手元のPCの.envだけです。冒頭の請求の件も、手元だけ新しくして本番が古いままだったのが原因でした
• 開発用と本番用の分離は、仕組みだけ入っています。 開発用のファイルには検証用の値、本番用のファイルには本番の値を配る設定はできますが、いま使っているアプリはまだありません。検証用の値が無い間は本番の値のまま配り、配るたびに注意を出します。本番のキーに触らず開発できる状態には、まだなっていません
• 元のファイルが漏れたら全部漏れます。 集めたのでそうなります。アクセス権を自分だけに絞り、クラウド同期のフォルダには置かず、控えも同じ扱いにしています。人と共有するなら、1Password CLIやDopplerのような専用の道具のほうが安全です
• 漏れたかもしれないときは、調べる前に失効させます。 発行元でキーを無効にして再発行し、元を直して配り、本番も直します。gitの履歴から消すのは失効のあとです

まとめ

アプリを1つずつ開いて確認・修正していた作業は、棚卸し・配布・点検の3つの操作になりました。それでも本番の登録と検証用の値の用意は手作業で残っていて、全部を自分で組むのは手間がかかります。キーの数が少なければ、FAQに挙げた無料の道具で足りることもあります。

同じようなAPIキー管理の悩みはありますか？

APIキーまわりで、いちばん面倒に感じている作業はどれでしょうか。

• 複数のアプリへの反映
• 開発と本番の切り替え
• キーの更新・失効
• 誤コミットの対策

XのSK Forgeへの返信かDM、または運営者情報にある問い合わせ先から教えてもらえるとうれしいです。同じ所で困っている声が集まれば、手順書やチェックリストにまとめることを考えます。