API Key Lifecycle

Signal Foundry の API キーは、発行して終わりではありません。作成、保存、利用、ローテーション、失効までを 1 つの lifecycle として扱います。

どこで管理するか

• チームアカウント: /home/<team-slug>/settings/api-keys

公開利用では team workspace の API キーを使います。チームでは settings.manage 権限が必要です。権限がない場合は API キー設定画面を見られても管理操作はできません。

1. 発行

発行時に指定するもの:

• name: 用途が分かるキー名
• expiresInDays: 任意。1 から 365 日、空欄なら無期限

発行すると、次が起きます。

• sf_live_ で始まる新しい平文キーが生成される
• 画面にはその平文キーが一度だけ表示される
• 同時に sf auth setup --base-url ... --no-open の初回コマンドが表示される

平文キーは再表示できません。必ずその場で保存し、必要な連携先へ設定してください。

2. 保存と初回接続

発行直後は次を実行します。

sf auth setup --base-url https://signal-foundry.app
sf auth show --json

保存済みのキーだけ差し替える場合は、次も使えます。

sf auth set-api-key <YOUR_API_KEY>
sf auth show --json

接続を消したい場合:

sf auth clear-api-key

3. 状態

画面上で見える主な状態は次です。

API 側の挙動:

• revoked: 401 api_key_revoked
• rotated: 401 api_key_rotated
• expired: 401 api_key_expired

4. ローテーション

ローテーションは、新しいキーを発行し、現在のキーを rotated に変える操作です。

現在の実装では、rotate 時に次が引き継がれます。

• キー名
• 有効期限

rotate 後にやること:

1. 新しい平文キーを保存する
2. 連携先のキーを置き換える
3. sf auth setup --no-open か sf auth set-api-key でローカル設定も更新する
4. sf auth show --json で preview が切り替わったことを確認する

古いキーは rotated になり、そのままでは使えません。

5. 失効

失効は、現在のキーを直ちに使えなくする操作です。

向いているケース:

• 不要になった一時キーを止めたい
• 漏えいの疑いがある
• 共有していたキーを完全に止めたい

一度失効したキーは元に戻しません。新しいキーを作り直してください。

6. 運用のおすすめ

• agent ごとにキーを分ける
• 本番、検証、smoke でキーを分ける
• 共有キーは rotate を前提にする
• 長く使わないキーは revoke する
• 発行後に usage summary が増えるか確認する

7. よくある失敗

• 平文キーを控えずに画面を閉じる
• rotate 後に古いキーを使い続ける
• 複数の用途で 1 本のキーを使い回す
• チームで settings.manage 権限がないのに管理しようとする
• billing / credit をチームで見たいのに個人 account のキーを使う

次に読むページ

• 利用状況の見方: Usage Summary
• 実際の認証ヘッダー: API キー認証