# 認証とリクエスト規約
> プログラムが使う API キー、呼び出し先、リクエストヘッダーです。

## API Key

Bearer 認証です。すべてのリクエストに付与します：

```text
Authorization: Bearer sk-<region>-...
```

キーの先頭には地域が入っています（例：`sk-row-...`）。`row` はそのキーの地域で、どの API に送るかを決めます。`row` は `https://api.beatra.ai/v1` です。地域が違うリクエストは拒否されます。キーはコンソール
[console.beatra.ai](https://console.beatra.ai) の **開発者向け → API キー** で作成します。secret が表示されるのは作成時の一度だけです。ローテーション時は、新しい key を作成 → デプロイを切り替え → 古い key を失効、の順で行います（新旧の key は並行して有効にできます）。

コンソールへのログインは、人がアカウントを管理するためのものです。API キーはプログラム、サービス、バックグラウンドの処理に使います。コンソールにログインした状態を、自動で動くプログラムに入れないでください。

## Base URL

```text
https://api.beatra.ai/v1
```

## リクエストヘッダー

| Header | 必須 | 説明 |
| --- | --- | --- |
| `Authorization` | はい | `Bearer <api_key>` |
| `Content-Type` | はい | `application/json`（ファイルアップロードを除く） |
| `Idempotency-Key` | 強く推奨 | 作成系の `POST` に付与。リトライでは同じ key を使用。重複排除は永続的で、同じ key は常に同じタスクに解決されます |
| `X-Request-Id` | 任意 | レスポンスにそのままエコーバック。トラブルシューティング時に最速の検索キー |

## 冪等性のルール

- 同じ論理操作のリトライ → **同一の** `Idempotency-Key` を使う
- ユーザーの意図が変わった → 新しい key に切り替える
- 同じ key で body が異なる → `409 idempotency_conflict`

レート制限のレスポンスヘッダーと 429 の処理は[レート制限](https://docs.beatra.ai/ja/docs/mechanisms/rate-limits)を参照してください。