# API-ключи

## Формат

```
agentapi-4e1d1cb6e9a2bf62c8a70f5d3b19e84c7a25f0d6b8e34179
└───┬───┘└──────────────────────┬──────────────────────┘
 префикс              48 hex-символов
```

Полная длина — 57 символов. Регулярное выражение для валидации:

```
^agentapi-[0-9a-f]{48}$
```

Ключ, не начинающийся с `agentapi-`, отклоняется с `401 Invalid API key format`.

## Жизненный цикл

1. **Создание** — требует положительного баланса и уникального имени в рамках аккаунта.
2. **Показ.** Ключ отдаётся в ответе **один раз**. Сохраните его сразу.
3. **Использование** — заголовком `x-api-key` или `Authorization: Bearer`.
4. **Отключение** (`active: false`) — обратимо, ключ перестаёт работать до включения обратно.
5. **Удаление** — необратимо.

Что из этого следует на практике:

- **Просмотреть существующий ключ невозможно** — ни через интерфейс, ни через API. Доступен только
  `postfix`, последние 4 символа, чтобы отличать ключи друг от друга в списке.
- **Ключ нельзя восстановить.** Если он утерян — удалите его и создайте новый.
- **Удаление необратимо.** Приложения, использующие этот ключ, немедленно получат 401.

## Управление через интерфейс

Раздел «Ваши API ключи» в [профиле](https://agentapi.ru/profile): создание, просмотр списка,
включение/отключение, удаление.

## Управление через API

Эти эндпоинты относятся к внутреннему API и требуют **JWT-авторизации пользователя**
(не ключа `agentapi-*`). Базовый URL — `https://api.agentapi.ru`, без префикса `/v1`.

JWT передаётся как `Authorization: Bearer <jwt>` либо в cookie `x-token`.

### Создать ключ

```
POST /api-key/create
```

```bash
curl https://api.agentapi.ru/api-key/create \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"apiKeyName": "My App Key"}'
```

Ответ:

```json
{
  "key": "agentapi-4e1d1cb6e9a2bf62c8a70f5d3b19e84c7a25f0d6b8e34179",
  "hashed": "9f2b7c4e8a1d5f3b6c9e2a7d4f1b8c5e3a6d9f2b7c4e8a1d5f3b6c9e2a7d4f1b",
  "postfix": "4179"
}
```

`key` возвращается только в этом ответе.

| Код | Причина |
|---|---|
| 403 | `Insufficient balance to create an API key` — баланс ≤ 0 |
| 404 | `API Key name already exists for this user` — имя занято |
| 404 | `User not found` |

### Список ключей

```
GET /api-key
```

```json
{
  "message": "Returns all apiKeys",
  "apiKeys": [
    {
      "id": "3f1a8c02-5b7e-4d61-9a3c-8e2f5d7b1c40",
      "apiKeyName": "My App Key",
      "postfix": "4179",
      "active": true,
      "createdAt": "2026-07-20T11:04:18.512Z"
    }
  ]
}
```

Сам ключ и служебные поля в этом ответе не возвращаются — только метаданные.

### Отключить или включить ключ

```
PATCH /api-key/update-activity/:id
```

```bash
curl -X PATCH https://api.agentapi.ru/api-key/update-activity/3f1a8c02-5b7e-4d61-9a3c-8e2f5d7b1c40 \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'
```

Отключённый ключ отдаёт `401 Invalid or inactive API key`. Обратимо: тем же запросом
с `"active": true`.

### Удалить ключ

```
DELETE /api-key/:id
```

Ответ — строка `Removed API key #<id>`. Необратимо.

## Ограничения

У ключей **нет** скоупов, ограничений по моделям, лимитов расхода и срока жизни — только
флаг `active`. Разделение прав между ключами не поддерживается: любой активный ключ
имеет полный доступ к API в рамках баланса аккаунта.

Rate limit также **не привязан к ключу** — он считается по IP-адресу, см.
[Ошибки и лимиты](https://agentapi.ru/docs/errors).

## Рекомендации по безопасности

- Храните ключ в переменных окружения или менеджере секретов, не в репозитории.
- Ключ даёт прямой доступ к балансу аккаунта — утечка приводит к расходу средств.
- Создавайте отдельные ключи под окружения (`dev`, `staging`, `prod`), чтобы отзыв одного
  не ломал остальные.
- Не используйте ключ в браузерном или мобильном коде: он будет виден пользователю.
  Проксируйте запросы через свой бэкенд.
- При подозрении на утечку — удалите ключ; отключения флагом недостаточно, если ключ
  скомпрометирован.