> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# API キーとセキュリティ

> BeatAPI キーの作成、権限の制限、ローテーション、無効化と、保存してはいけない場所を説明します。

# API キーとセキュリティ

## キーはどこで作成できますか？

[ダッシュボード → API キー](https://beatapi.io/dashboard/apikeys)で作成します。キーは再表示されないため、表示されたときにコピーしてください。

## キーはいくつ作成するべきですか？

BeatAPI を呼び出すアプリケーション、ツール、環境ごとに 1 つずつ作成してください。

費用はかからず、すぐにメリットがあります。`GET /v1/usage` の `by_api_key` で追加の計測実装なしに利用額を区別できます。漏えいや異常な動作があったキーだけを無効にできるため、ほかのサービスを止めずに対処できます。

開発、ステージング、本番でキーを共有しないでください。

## キーを保存してはいけない場所は？

ユーザーや第三者が読み取れる場所には保存しないでください。

* ブラウザーの JavaScript やクライアント側のバンドル。ブラウザーに配信される内容は公開情報です。
* モバイルアプリケーション。逆コンパイルで取り出せます。
* 公開リポジトリ、または将来公開する可能性のある非公開リポジトリ。
* ログ、エラーレポート、スクリーンショット、サポートチケット。
* URL のクエリ文字列。プロキシ、ブラウザーの履歴、サーバーログに記録されます。

キーを送信する正しい場所はヘッダーです。`Authorization: Bearer <key>` を使用してください。

## リポジトリにキーを含めない方法は？

環境変数を使用し、その設定ファイルをバージョン管理から除外します。

```bash
read -rsp "BeatAPI API key: " BEATAPI_API_KEY && echo
export BEATAPI_API_KEY
```

この方法ならシェルの履歴にもキーが残りません。`.env`、`~/.codex/auth.json`、キーを含むツールの設定ファイルを `.gitignore` に追加してください。

対応する連携では、設定ファイルにキーを貼り付けるより環境変数を優先してください。[Codex CLI](/integrations/codex-cli) の `env_key` も、そのための設定です。

## キーが漏えいした場合は？

まず[ダッシュボード → API キー](https://beatapi.io/dashboard/apikeys)で無効にし、その後に新しいキーを作成して利用箇所を更新します。無効化は即座に反映されます。

この順番を守ってください。先に新しいキーへ切り替えて後から無効にすると、その間に漏えいしたキーで残高を消費される可能性があります。

その後、`GET /v1/usage` の `by_api_key` で、身に覚えのない利用がないか確認します。

## どのくらいの頻度でキーを交換するべきですか？

継続できる周期を決めて交換してください。また、アクセス権のある人が離任したときや、キーが露出した可能性があるときは直ちに交換します。コンポーネントごとにキーを分ければ、交換対象のデプロイも 1 つに限定できます。

## ブラウザーから BeatAPI を直接呼び出せますか？

API キーを使う呼び出しはできません。Realtime API ではサーバーが Session を作成し、その Session に限定された短寿命の `client_secret` をブラウザーに渡します。[Realtime API](/realtime-api) を参照してください。その他のエンドポイントはサーバー側からのみ呼び出してください。

生成したメディアの読み取りは例外です。タスクのアーティファクト URL はクエリ文字列に署名付きの認証情報を含み、そのオブジェクトだけへのアクセスを許可します。ブラウザーの `<img>` や `<video>` から、ヘッダーなしで読み込めます。

## データは学習に使われますか？

BeatAPI はリクエストを学習に使用しません。顔、声、その他の個人情報を送信する前や、他者の代わりにデータを処理する前に、[プライバシーポリシー](https://beatapi.io/privacy-policy)と[利用規約](https://beatapi.io/terms-of-service)を確認してください。

## Webhook が BeatAPI から届いたことを確認するには？

JSON を解析する前に、**リクエストの生のバイト列**に対して署名を検証します。本文を再シリアライズすると内容が変わり、署名が一致しなくなります。古い通知の再送を防ぐため、タイムスタンプも確認してください。[Webhooks](/webhooks) を参照してください。

署名を検証しない Webhook エンドポイントは、認証なしでシステムへ書き込める経路になります。検証失敗は単なる不具合ではなく、攻撃の可能性として扱ってください。

## 何がログに記録されますか？

サポートと課金のため、リクエストは `request_id` とともに記録されます。問題を報告するときは、その ID を添えてください。キー自体は送らないでください。