APIキーのライフサイクル

Signal Foundry の通常の人間 / エージェント接続は sf login です。API キーは、プロダクト組み込み、backend job、scheduled job、.env / secret store から直接 HTTP API を呼ぶための service 認証情報 として扱います。発行して終わりではなく、作成、保存、利用、ローテーション、失効までを 1 つの lifecycle として管理します。

どこで管理するか

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

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

1. 発行

発行時に指定するもの:

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

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

• sf_live_ で始まる新しい平文キーが生成される
• 画面にはその平文キーが一度だけ表示される
• secret store / .env へ設定するための値が一度だけ表示される

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

2. 保存と接続

人間/エージェントの初回接続は API key ではなく sf login です。

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

発行直後の key は product backend、job 実行ner、CI などの secret store / .env に保存します。CLI の初期設定へ貼り付ける導線にはしません。

3. 状態

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

API 側の挙動:

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

4. ローテーション

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

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

• キー名
• 有効期限

rotate 後にやること:

1. 新しい平文キーを保存する
2. 連携先のキーを置き換える
3. 直接 API連携 の疎通を確認する

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

5. 失効

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

向いているケース:

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

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

6. 運用のおすすめ

• human / エージェント onboarding は sf login に寄せる
• 本番、検証、smoke でキーを分ける
• 共有キーは rotate を前提にする
• 長く使わないキーは revoke する
• 発行後に usage summary が増えるか確認する

7. よくある失敗

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

次に読むページ

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