API キーとセキュリティ
API キーとセキュリティ
キーはどこで作成できますか？
ダッシュボード → API キーで作成します。キーは再表示されないため、表示されたときにコピーしてください。
キーはいくつ作成するべきですか？
BeatAPI を呼び出すアプリケーション、ツール、環境ごとに 1 つずつ作成してください。
費用はかからず、すぐにメリットがあります。GET /v1/usage の by_api_key で追加の計測実装なしに利用額を区別できます。漏えいや異常な動作があったキーだけを無効にできるため、ほかのサービスを止めずに対処できます。
開発、ステージング、本番でキーを共有しないでください。
キーを保存してはいけない場所は？
ユーザーや第三者が読み取れる場所には保存しないでください。
- ブラウザーの JavaScript やクライアント側のバンドル。ブラウザーに配信される内容は公開情報です。
- モバイルアプリケーション。逆コンパイルで取り出せます。
- 公開リポジトリ、または将来公開する可能性のある非公開リポジトリ。
- ログ、エラーレポート、スクリーンショット、サポートチケット。
- URL のクエリ文字列。プロキシ、ブラウザーの履歴、サーバーログに記録されます。
キーを送信する正しい場所はヘッダーです。Authorization: Bearer <key> を使用してください。
リポジトリにキーを含めない方法は？
環境変数を使用し、その設定ファイルをバージョン管理から除外します。
この方法ならシェルの履歴にもキーが残りません。.env、~/.codex/auth.json、キーを含むツールの設定ファイルを .gitignore に追加してください。
対応する連携では、設定ファイルにキーを貼り付けるより環境変数を優先してください。Codex CLI の env_key も、そのための設定です。
キーが漏えいした場合は？
まずダッシュボード → API キーで無効にし、その後に新しいキーを作成して利用箇所を更新します。無効化は即座に反映されます。
この順番を守ってください。先に新しいキーへ切り替えて後から無効にすると、その間に漏えいしたキーで残高を消費される可能性があります。
その後、GET /v1/usage の by_api_key で、身に覚えのない利用がないか確認します。
どのくらいの頻度でキーを交換するべきですか？
継続できる周期を決めて交換してください。また、アクセス権のある人が離任したときや、キーが露出した可能性があるときは直ちに交換します。コンポーネントごとにキーを分ければ、交換対象のデプロイも 1 つに限定できます。
ブラウザーから BeatAPI を直接呼び出せますか？
API キーを使う呼び出しはできません。Realtime API ではサーバーが Session を作成し、その Session に限定された短寿命の client_secret をブラウザーに渡します。Realtime API を参照してください。その他のエンドポイントはサーバー側からのみ呼び出してください。
生成したメディアの読み取りは例外です。タスクのアーティファクト URL はクエリ文字列に署名付きの認証情報を含み、そのオブジェクトだけへのアクセスを許可します。ブラウザーの <img> や <video> から、ヘッダーなしで読み込めます。
データは学習に使われますか？
BeatAPI はリクエストを学習に使用しません。顔、声、その他の個人情報を送信する前や、他者の代わりにデータを処理する前に、プライバシーポリシーと利用規約を確認してください。
Webhook が BeatAPI から届いたことを確認するには？
JSON を解析する前に、リクエストの生のバイト列に対して署名を検証します。本文を再シリアライズすると内容が変わり、署名が一致しなくなります。古い通知の再送を防ぐため、タイムスタンプも確認してください。Webhooks を参照してください。
署名を検証しない Webhook エンドポイントは、認証なしでシステムへ書き込める経路になります。検証失敗は単なる不具合ではなく、攻撃の可能性として扱ってください。
何がログに記録されますか？
サポートと課金のため、リクエストは request_id とともに記録されます。問題を報告するときは、その ID を添えてください。キー自体は送らないでください。