APIキーを発行して安全に管理する

発行の仕組み

APIキーは1アカウントにつき1つです。初回のGoogleログインでアカウントが登録されたときに自動発行され、平文のキーは発行直後の画面で一度だけ表示されます。名前、スコープ、有効期限の設定はなく、同じキーでそのアカウントのすべてのAPI操作を認証します。

画面を離れたあとに現在のキーを再表示することはできません。安全な保管先へ登録してから画面を閉じてください。

シェルで画面に表示せず設定する

次の例では入力内容を画面へ表示せず、現在のシェルの環境変数に設定します。

read -rsp 'ROR_API_KEY: ' ROR_API_KEY
export ROR_API_KEY
printf '\n'

以降のリクエストでは、キーの値を直接書かずに $ROR_API_KEY をBearer認証へ使います。echo、デバッグ用の set -x、curl -v など、キーや認証ヘッダーを出力する操作は避けてください。

安全に取り扱う

• APIキーをソースコード、チャット、ログ、スクリーンショットへ貼り付けない
• ZIP、.env、ブラウザへ配信するJavaScriptへ含めない
• CIでは暗号化されたsecretとして登録し、必要なジョブだけに渡す
• Idempotency-Key にAPIキーやほかの秘密情報を使わない
• https://ror.jp/api/v1/ 以外へ認証ヘッダーを送らない

このAPIキーには操作別のスコープがありません。漏えいすると、そのアカウントが所有するロールの取得、変更、削除に使われるおそれがあります。

紛失・漏えい時は再生成する

APIキー管理画面から再生成すると、新しいキーが一度だけ表示され、以前のキーは直ちに無効になります。利用中のCIやツールをすべて新しいキーへ更新してください。

再生成後に以前のキーを使うと、APIは 401 unauthorized を返します。