APIキーのライフサイクル

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

どこで管理するか

チームワークスペースの API キー設定画面で管理します。

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

チームでは settings.manage 権限を持つメンバーが管理します。権限がない場合は、API キー設定画面を見られても管理操作はできません。1 人で使う場合も、自分が owner のチームワークスペースでキーを作ります。

個人アカウントの設定画面は、既存ユーザーや内部検証のために残る場合があります。billing とクレジットを運用する正面入口はチームワークスペースです。

設定画面でできること:

• 名前付きで API キーを発行する
• 任意で有効期限を付ける
• 既存キーを rotate する
• 既存キーを revoke する
• 直近 30 日の利用量を確認する

1. 発行

発行時に指定するもの:

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

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

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

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

2. 保存と接続

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

sf login --json
sf auth show --json

発行直後のキーは、product backend、job 実行環境、CI などの secret store / .env に保存します。CLI の初期設定へ貼り付ける導線にはしません。平文キーは docs、issue、prompt、shell history、エージェントの会話ログにも書かないでください。

3. 送り方

直接 HTTP API を呼ぶ場合は、次のどちらかのヘッダーで API キーを送ります。

• x-api-key: <API_KEY>
• Authorization: Bearer <API_KEY>

curl \
  -H 'x-api-key: <SIGNAL_FOUNDRY_API_KEY>' \
  'https://signal-foundry.app/api/signal-foundry/companies?q=7203&limit=3'

curl \
  -H 'Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>' \
  'https://signal-foundry.app/api/signal-foundry/companies/7203/profile'

認証情報は 1 リクエストにつき 1 つだけ送ります。

• x-api-key と Authorization: Bearer の両方で API キーを送り、値が一致しない場合は 400 api_key_conflict です。
• x-api-key と Authorization: Bearer <JWT>(WorkOS JWT)の同時送信は拒否されます。これは API キーを 2 本送った場合とは別のケースです。

挙動:

• 正しいキーなら auth_mode=api_key で記録される
• 無効なキーなら 401 invalid_api_key
• minute / day 上限を超えると 429 rate_limit_exceeded

正規接続先には https://signal-foundry.app を使います。Preview URL は接続先にしません。

ここで扱うのは、現在の読み取り API の認証方法だけです。書き込み系 API の将来仕様は含みません。

4. 状態

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

API 側の挙動:

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

5. ローテーション

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

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

• キー名
• 有効期限

rotate 後にやること:

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

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

6. 失効

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

向いているケース:

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

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

7. 運用のおすすめ

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

8. よくある失敗

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

次に読む

• 利用状況の見方: 利用状況の見方