UnifyPort APIキーを無停止でローテーションする方法

UnifyPort APIキーを無停止で交換するには、最初に rotate エンドポイントを呼び出してはいけません。POST /v1/api-keys/{key_id}/rotate が成功すると、旧キーは直ちに無効になります。先に2本目の有効なキーを作成し、一度だけ表示されるシークレットを安全に保存し、すべての呼び出し元へデプロイします。GET /v1/workspace で確認してから、旧キーを inactive に変更します。

要点

• rotate エンドポイントは即時切り替えで、旧キーの猶予期間はありません。
• 無停止交換では、作成、デプロイ、確認、無効化の順で一時的に2本のキーを有効にします。
• 新規作成またはローテーションされた完全なキーは data.api_key に一度だけ返され、後から取得できません。
• キー一覧には key_prefix や状態などのメタデータだけが表示されます。
• 通常のローリングデプロイでは「新規作成後に旧キーを無効化」を使い、即時失効が必要な場合だけ rotate を使います。

rotate を先に実行すると本番が止まる理由

Rotate API key リファレンスでは、次の操作が定義されています。

POST /v1/api-keys/{key_id}/rotate

この操作は新しいキーレコードを作り、新しいシークレットを一度だけ返します。同時に旧キーを直ちに無効にします。古い認証情報をすぐ失効させたい場合には適切ですが、Webプロセス、キューワーカー、定期ジョブ、別リージョンのインスタンスが旧値を読み続けていると、401 invalid_api_key が発生します。

ローリングデプロイには、新旧の設定が短時間共存する期間があります。認証情報を一斉に切り替えるとその期間がなくなるため、アプリケーション自体が正常でも認証に失敗します。

NIST SP 800-53 の認証子管理には、認証子の変更・更新という一般的な考え方が含まれます。ただし運用順序は製品の実際の契約に合わせる必要があります。UnifyPort は複数の APIキーレコードを保持でき、rotate は旧キーを即時失効させます。

無停止APIキーローテーション手順

1. すべての呼び出し元を洗い出す

https://api.unifyport.ai に X-Api-Key を送る箇所を一覧化します。公開API、バックグラウンドワーカー、返信APIを呼ぶWebhook処理、定期ジョブ、本番運用ツール、ヘルスチェックが対象です。

APIキーとWebhookの signing_secret は別物です。APIキーはUnifyPort REST APIへのリクエストを認証します。signing_secret は受信Webhookの署名を検証します。後者については、Webhook HMAC、再送対策、リトライのガイドを参照してください。

List API keys で既存レコードを確認できます。

curl https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY"

レスポンスには id、name、key_prefix、status が含まれますが、完全なシークレットは表示されません。

2. 2本目の有効なキーを作成する

rotate ではなく Create API key を使います。

curl -X POST https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production 2026-08 cutover",
    "prefix": "dk_live"
  }'

成功時の 201 レスポンスは、data.key にメタデータ、data.api_key に完全な新シークレットを返します。値は承認済みのシークレット管理基盤へ直接保存してください。デプロイログ、チケット、チャットには出力しません。

デプロイ前に一度きりの値を失った場合は、別のキーを作成し、未使用レコードを無効にします。プレフィックスから完全な値を復元することはできません。

3. デプロイ前に新キーを確認する

新しいシークレットで読み取り専用の認証確認を行います。

curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY"

成功すれば、新キーが対象ワークスペースに解決されることを確認できます。ただし、すべてのアプリケーションインスタンスが新値を読み込んだ証明にはなりません。

次にデプロイが参照するシークレットを更新し、呼び出し元ごとに段階的に反映します。この間は旧キーを active のまま残します。LINEを中心に日本向けサポートを運用している場合も、LINE処理だけでなく、WhatsAppやTelegramを扱う共通ワーカー、夜間ジョブ、返信処理まで確認してください。

4. 全サービスが新しい認証情報を使っているか確認する

旧キーを止める前に、次を確認します。

• WebおよびAPIインスタンスのデプロイが完了した。
• キューコンシューマーが再起動または設定を再読込した。
• 定期ジョブが次回実行時に新しいシークレットを読む。
• メッセージ返信・送信経路で認証済みリクエストが成功する。
• 緊急用スクリプトがローカルにコピーした旧値へ依存していない。

判断材料はアプリケーション側のリクエスト結果とデプロイ状態です。UnifyPortのキー一覧に、キーごとの最終利用時刻は文書化されていません。返されないデータを前提に移行完了と判断しないでください。

ダッシュボードから運用を始めたチームは、ダッシュボードとAPIキー管理のお知らせも確認できます。本記事は、稼働中システムに必要なデプロイ順序を補います。

5. 旧キーを無効化する

すべての呼び出し元が新シークレットへ移行した後、新キーを使って Update API key status を呼びます。

curl -X PATCH "https://api.unifyport.ai/v1/api-keys/$OLD_KEY_ID" \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"inactive"}'

文書化された状態は active と inactive です。無効化後、旧キーで制御された読み取り専用リクエストを1回行い、401 invalid_api_key になることを確認します。実際の顧客処理をテストに使わないでください。

最後に、デプロイ設定、ローカル環境ファイル、CI変数、一時的な移行資料から旧値を削除します。運用記録にはキーID、名前、状態、担当者、切り替え時刻など、秘密ではない情報だけを残します。

即時rotateを使うべき場面

POST /v1/api-keys/{key_id}/rotate を使うのは、旧認証情報の即時失効そのものが要件である場合です。認証情報が外部に出た可能性がある場合や、すべての呼び出し元を同時に切り替えられるメンテナンス時間が該当します。

その場合は次の順序です。

1. 旧キーを保持する呼び出し元を停止または隔離する。
2. 管理された運用経路から rotate を実行する。
3. data.api_key を一度だけ取得して保存する。
4. すべてのシークレット利用者を更新する。
5. トラフィックを戻し、認証を確認する。

この方式は継続稼働より失効速度を優先します。認証情報の露出が疑われる場合は、可用性だけを理由に2本のキーを長時間有効にせず、インシデント手順に従ってください。

制限とトレードオフ

短い2キー併用期間には、両方の認証情報がワークスペースを認証できます。期間を必要最小限にし、シークレットへアクセスできる人とシステムを限定してください。UnifyPortの導入ドキュメントでは、X-Api-Key は1つのワークスペースに解決され、その範囲へのアクセスを与えると説明されています。これはエンドポイント別権限の移行ではありません。

また、この手順はWebhookの signing_secret、各プラットフォームのログイン情報、インポート済みセッションを変更しません。秘密の種類ごとに利用者と障害モードが異なるため、別々に変更・検証します。

FAQ

UnifyPort APIキーのrotateに猶予期間はありますか？

文書化されたrotateエンドポイントに猶予期間はありません。成功時に旧キーは直ちに無効になります。重複期間が必要なら先に2本目を作成します。

新しいAPIキーを後からもう一度取得できますか？

できません。完全な値は data.api_key に一度だけ返されます。その後の一覧にはプレフィックスや状態などのメタデータだけが表示されます。

新キーを安全にテストする方法は？

新しい X-Api-Key で GET /v1/workspace を呼びます。その後、すべてのデプロイ済み呼び出し元が同じ新シークレットを読み込んだことを確認します。

rotateと「作成後に無効化」はどう選びますか？

通常のローリングデプロイでは作成後に無効化します。即時失効が必要で、旧キー利用者を隔離済みの場合はrotateを使います。

APIキーと signing_secret は同じですか？

いいえ。X-Api-Key はREST API呼び出しを認証し、signing_secret はWebhookのHMAC-SHA256署名を検証します。

次のステップ

Create API key リファレンスを開き、本番用の並行キーを作成してください。旧キーの状態を変える前に、上記5つのゲートを完了します。

情報源

2026年8月17日に確認。

• UnifyPort: Create API key
• UnifyPort: List API keys
• UnifyPort: Update API key status
• UnifyPort: Rotate API key
• NIST SP 800-53 Revision 5