# 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.ai/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.ai](https://console.beatra.ai) → **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.ai/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.ai/en/docs/mechanisms/rate-limits).