やること
- 先に新しいキーを発行し、旧キーは新キーの動作確認後にのみ失効させることで、ダウンタイムなしにローテーションを行う。
- 漏洩したキーは直ちに失効させる — 全リージョンへの反映は最大60秒。
- キーは環境変数またはシークレットマネージャーに保存し、コードには記載しない。アクセス権を持つチームメンバーが離脱した際はローテーションを行う。
API キーは長期間有効なベアラートークンであるため、定期的なローテーションや、漏洩時の即座の失効を適切に行うことが重要です。この記事では、両方のケースについて手順を説明します。
ダウンタイムなしでキーをローテーションする#
ローテーションとは、古いキーを廃止する前に新しいキーを発行することを指します。これにより、連携が未認証になる期間を作ることなく移行できます。
- Settings → API keys に移動し、Generate key をクリックします。
- 新しいキーに、用途が明確な名前を付けます（例：
production-v2）。 - 置き換え対象のキーと同じロールを選択します。
- トークンをコピーします。トークンは一度しか表示されません。
- 環境変数またはシークレットマネージャーを新しいトークンで更新し、デプロイします。
- 新しいキーが有効になり、正常に動作していることを確認したら（Last used カラムを確認してください。数分以内に更新されるはずです）、Settings → API keys に戻り、古いキーの Revoke をクリックします。
新しいキーの動作が確認できるまで、古いキーは有効なままにしておいてください。デプロイが完了する前に失効させると、トラフィックが 401 エラーになります。
漏洩したキーを直ちに失効させる#
キーが露出した場合（公開リポジトリへのプッシュ、ログへの漏洩、クライアントサイドのバンドルへの混入など）、調査の前にまず失効させてください。
- Settings → API keys で、名前またはプレフィックスから該当するキーを探します（トークン全文は表示されませんが、プレフィックスはテーブルで確認できます）。
- Revoke をクリックします。失効設定は 60 秒以内にすべてのリージョンに反映されます。
- 代替のキーを発行し、シークレットを更新します。
- 失効させたキーの Last used タイムスタンプを確認し、露出していた期間の推定や、不正なアクティビティの監査が必要かどうかを判断してください。
失効したキーは、記録のために revoked バッジが付いた状態でテーブルに保持されます。これらを再度有効化することはできません。
シークレットを安全に更新する#
標準的なパターンは、キーをコード内ではなく環境変数に保存することです。
# .env.local (決してコミットしないでください)
ELIDO_API_KEY=elido_live_xxx...
import { ElidoClient } from "@elido/sdk";
const client = new ElidoClient({ apiKey: process.env.ELIDO_API_KEY! });
CI パイプラインでは、プラットフォームのシークレットストア（GitHub Actions secrets、GitLab CI variables など）を使用し、アクセス権を持つメンバーがチームを離れる際などには必ずローテーションを行ってください。
稼働中の連携への影響#
キーを失効させた際、すでにトークンが送信済みの処理中のリクエストはそのまま完了します。認証の検証はリクエストの開始時に行われ、レスポンスの途中では行われないためです。失効後に開始されたリクエストは 401 Unauthorized を返します。SDK は 401 エラー時にリトライを行わないため（ループを防ぐため）、連携は即座に失敗し始めます。
短いオーバーラップ期間を計画してください。新しいキーが本番環境でアクティブになったことを確認するまで、古いキーを有効に保つようにします。
トラブルシューティング#
作成したばかりのキーで 401 が発生する。 作成時に表示されるトークンは、シークレットのサフィックスを含む完全なキーです。テーブルからプレフィックス（例：elido_abc123）のみをコピーしても動作しません。プレフィックスは表示専用です。新しいキーを再発行し、完全なトークンをコピーしてください。
Revoke ボタンが表示されない。 そのキーはおそらくすでに失効しています。失効したキーには revoked バッジが表示され、アクションボタンは表示されません。また、正しいワークスペースを見ているか確認してください。キーはワークスペースごとにスコープされています。
60 秒の反映待ち。 キーを失効させた後、一瞬だけリクエストが成功し続けることがありますが、これは想定された挙動です。エッジノードは Redis pub/sub を介して失効情報を同期しており、最悪の場合で約 60 秒のタイムラグが発生します。
リストからキーが消えた。 監査目的のため、失効したキーも無期限にテーブルに保持されます。見つからない場合は、リストにフィルタがかかっていないか確認してください。デフォルトではアクティブなキーのみを表示するフィルタはありませんが、名前フィールドでのテキスト検索により、一致しない行が非表示になっている可能性があります。