# Authentication & request conventions
> API keys, base URL, and headers for agent clients.

## API key

Bearer authentication; every request carries:

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

Keys embed their region in the prefix (`sk-row-...`). `row` is the region in that example, and it selects the API host (`https://api.beatra.cn/v1` for `row`). A key used on the wrong host is rejected. Use the API host that
matches the key's region. Create keys in the console at
[console.beatra.cn](https://console.beatra.cn) → **Developer → API keys**. The
secret is shown only once, at creation. To rotate: create a new key → switch your deployment → revoke the old key (old and new can be active in parallel).

Console sign-in is for humans managing the account. API keys are for agents,
services, MCP adapters, and background jobs. Do not embed Console session
cookies into agent runtimes.

## Base URL

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

## Request headers

| Header | Required | Description |
| --- | --- | --- |
| `Authorization` | Yes | `Bearer <api_key>` |
| `Content-Type` | Yes | `application/json` (except file uploads) |
| `Idempotency-Key` | Strongly recommended | Send on create-style `POST` requests; reuse the same key on retries. Dedupe is durable: the same key always resolves to the same task |
| `X-Request-Id` | Optional | Echoed back verbatim in the response; the fastest lookup key when troubleshooting |

## Idempotency rules

- Retries of the same logical operation → the **same** `Idempotency-Key`;
- The user's intent changed → use a new key;
- Same key with a different body → `409 idempotency_conflict`.

For rate-limit response headers and 429 handling, see [Rate limits](https://docs.beatra.cn/en/docs/mechanisms/rate-limits).

## Connect an MCP host (OAuth)

Add `https://mcp.beatra.cn/mcp` to a host that supports standard MCP OAuth.
The host finds Beatra's sign-in on its own, registers itself, and opens a Beatra page in your browser.
Sign in, check where the connection goes, and select **Allow**. No API key, no token to copy.

What a connection can do:

- create images, video, music, and speech with your Beatra credits, and use the public social data tools;
- use and manage your voices (including cloned voices) and digital avatars;
- view and cancel tasks, and save and read your works;
- see your balance and credit history (including top-ups).

How long it lasts:

- Hosts that sign in with OAuth stay signed in: they renew in the background. If a host goes unused for a year, sign in again.
- Connections made with the [headless connect command](https://docs.beatra.cn/en/docs/agent-connect) last until you disconnect them, or until they go unused for a year.

Manage connections in the console under **Devices → Connected apps**: see each app, where it connects, when it
was first connected and last used, and disconnect it. If an app's sign-in is used from a copy, Beatra
disconnects that app to protect your account and says so on that page; connect it again from the app.

Agents that run Beatra Skills sign in through the Skill instead; see [Quickstart](https://docs.beatra.cn/en/docs/quickstart).