API キーは、利用者を介さないサーバー間連携のための認証情報です。夜間バッチ、人事システムとのデータ同期、BI ツールへの連携などに使います。
アプリのトークンと API キーの使い分け
| アプリのトークン（OAuth） | API キー | |
|---|---|---|
| 誰として動くか | サインインした利用者本人 | 組織そのもの（人に紐づかない） |
| 権限の決まり方 | アプリの許可 ∩ 要求 ∩ 本人の権限 | キーに設定したスコープそのまま |
| 向いている用途 | モバイルアプリ、社内ポータルの画面 | バッチ、システム連携、定期実行 |
| 有効期限 | アクセストークン 1 時間（更新可） | 失効させるまで有効（期限設定も可） |
API キーは、設定したスコープをそのまま持ちます。
アプリのトークンのように「利用者本人の権限との共通範囲」で絞られることはありません。
write:members を付けたキーは、誰の権限も介さずメンバーを変更できます。
そのため、管理者向けスコープを含むキーの発行は組織管理者のみが行えます。
使ってはいけない場所
モバイルアプリやブラウザーの JavaScript に API キーを埋め込まないでください。
配布物は解析でき、ブラウザーの通信は誰でも見られます。埋め込んだ時点で、そのキーは公開されたものとして扱う必要があります。
利用者の端末で動くものは、必ず OAuth のサインイン（「Manabu2 アカウントでサインインさせる」）を使ってください。
発行する
API キーは組織単位で発行します。発行できるのは 開発者 または 組織管理者 です。
発行時に決めるのは次の 2 つです。
- 名前 — 何に使うキーか分かるように。例：「人事システム夜間同期」「BI 連携（本番）」
- スコープ — そのキーができる操作。詳しくは「スコープの選び方」を参照してください
キーの本体は発行直後に 1 度だけ表示されます。
当社側ではハッシュ化して保存しているため、後から取り出すことはできません。一覧画面には先頭の識別子と末尾 4 文字だけが表示されます。
使い方
次のどちらの形式でも送れます。
X-Api-Key: mnb_live_…
Authorization: Bearer mnb_live_…
mnb_live_ という接頭辞が付いているため、ログや貼り付けの中で見つけたときに「これは Manabu2 の API キーだ」と判別できます。
保管とローテーション
推奨
- クラウドのシークレット管理サービスに保管する
- 環境変数として実行時に読み込む
- 用途ごとにキーを分ける（漏れたとき、影響範囲を切り分けられます）
- 本番と検証で別のキーを使う
避けるべき
- ソースコードに直接書く
- 設定ファイルごと Git にコミットする
- チャットやメールで共有する
- 1 つのキーを複数のシステムで使い回す
Git にコミットしてしまった場合、履歴からファイルを消してもキーが漏れた事実は変わりません。過去のコミットにも、クローンした人の手元にも残っています。必ず失効させて新しいキーを発行してください。
漏れた疑いがあるとき
- 該当のキーをすぐ失効させます
- 新しいキーを発行し、連携先の設定を更新します
- 不審な API 呼び出しがなかったかを確認します
失効は即座に効きます。有効期限切れを待つ必要はありません。用途ごとにキーを分けておくと、この作業で止まるシステムを 1 つに限定できます。
制限の確認
API には呼び出し回数の上限があります。認証済みの呼び出しは 1 分あたり 300 回です。上限を超えると 429 が返り、Retry-After ヘッダーに待つべき秒数が入ります。詳しくは API ドキュメントを参照してください。
