# Аутентификация

Все эндпоинты инференса требуют API-ключ. Поддерживаются два заголовка — используйте любой.

## Вариант 1: `x-api-key`

Основной вариант платформы.

```bash
curl https://api.agentapi.ru/v1/ai/chat/completions \
  -H "x-api-key: agentapi-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4.1","messages":[{"role":"user","content":"Привет!"}]}'
```

## Вариант 2: `Authorization: Bearer`

Именно этот заголовок отправляют OpenAI SDK и большинство плагинов для редакторов, поэтому
они работают без дополнительной настройки заголовков.

```bash
curl https://api.agentapi.ru/v1/ai/chat/completions \
  -H "Authorization: Bearer agentapi-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4.1","messages":[{"role":"user","content":"Привет!"}]}'
```

Значение после `Bearer ` должно быть самим ключом `agentapi-*`. Передавать здесь JWT
пользователя нельзя — эндпоинты инференса принимают только API-ключи.

## Приоритет заголовков

Если присланы оба заголовка, используется **`x-api-key`**; `Authorization` игнорируется.
Дублировать их не нужно — при работе через SDK достаточно штатного параметра `apiKey`.

## Порядок проверок

Ключ проходит проверки в этом порядке, и первая неудачная возвращает 401:

1. Заголовок присутствует → иначе `API key is required in x-api-key or Authorization header`
2. Ключ начинается с `agentapi-` → иначе `Invalid API key format`
3. Ключ существует и активен → иначе `Invalid or inactive API key`
4. Ключ связан с существующим пользователем → иначе `API key not found`

Формат ответа:

```json
{
  "statusCode": 401,
  "message": "Invalid or inactive API key",
  "error": "Unauthorized"
}
```

## CORS

Для внешнего API (`/v1*`) CORS открыт: разрешённые заголовки — `Content-Type`,
`Authorization`, `x-token`, `x-api-key`.

Технически это позволяет обращаться к API прямо из браузера, но **так делать не нужно**:
ключ станет доступен любому пользователю страницы, а вместе с ним — и баланс аккаунта.
Проксируйте запросы через свой сервер.

## Внутреннее API

Управление аккаунтом (`/api-key/*`, `/billing/*`, `/user/*`, `/stats/*`) использует
не API-ключ, а **JWT** — в заголовке `Authorization: Bearer <jwt>` либо в cookie `x-token`.
Эти эндпоинты живут на том же хосте, но без префикса `/v1`.

| | Инференс | Управление аккаунтом |
|---|---|---|
| Префикс | `/v1/ai/*` | без префикса |
| Учётные данные | ключ `agentapi-*` | JWT пользователя |
| Заголовок | `x-api-key` или `Authorization: Bearer` | `Authorization: Bearer` или cookie `x-token` |