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

## API Key

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

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

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

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

## Base URL

```text
https://api.beatra.cn/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.cn/ja/docs/mechanisms/rate-limits)を参照してください。

## MCP ホストの接続（OAuth）

標準 MCP OAuth に対応したホストに `https://mcp.beatra.cn/mcp` を追加します。ホストが認証先を見つけて登録し、ブラウザーで Beatra を開きます。ログイン後、接続先を確認して **許可** を選んでください。API キーやトークンをコピーする必要はありません。

接続したアプリは、Beatra のクレジットを使った画像・動画・音楽・音声の生成、公開ソーシャルデータの取得、音声やアバターの管理、タスクの表示とキャンセル、作品の保存と閲覧、残高とクレジット履歴の閲覧ができます。

OAuth に対応したホストはバックグラウンドで認証を更新します。1 年間使われなかった場合は再ログインしてください。[ヘッドレス接続コマンド](/ja/docs/agent-connect)による接続は、解除されるか、1 年間使われなくなるまで有効です。

コンソールの **デバイス → 接続済みアプリ** で接続先、初回接続、最終使用を確認し、接続を解除できます。更新用の認証情報の再利用が確認されると、その認可は失効し、このページに理由が表示されます。ホストから再接続してください。

Beatra Skill を使うエージェントは Skill のログイン手順を使います。[クイックスタート](/ja/docs/quickstart)を参照してください。