API-ключи

Формат

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

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

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

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

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

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

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

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

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

Раздел «Ваши API ключи» в профиле: создание, просмотр списка, включение/отключение, удаление.

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

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

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

Создать ключ

POST /api-key/create

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

Ответ:

{
  "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

{
  "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

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-адресу, см. Ошибки и лимиты.