# API-ключи и права

> Формат API-ключа BotHunt, права и пресеты, ограничение по сайтам, сроку и IP-адресам, отзыв ключа и журнал действий через API.

Источник: https://bothunt.ru/docs/api/klyuchi · обновлено 2026-10-26

Ключ — пропуск вашего скрипта или сервиса в API. Он действует от имени вашего аккаунта, но только в пределах выбранных прав и сайтов. Заведите отдельный ключ на каждую интеграцию: тогда один можно отозвать, не трогая остальные.

[Открыть «API» в кабинете](https://bothunt.ru/dashboard/account/api)

## Как выглядит ключ

`bhk_` и 48 латинских букв и цифр. Первые 8 символов после `bhk_` — префикс: по нему ключ видно в кабинете и в журнале. Сам ключ показывается один раз, при создании.

> **Осторожно.** Не публикуйте ключ в репозитории, в коде страницы или в браузерном JavaScript: с ним можно менять правила и DNS вашего сайта. Если ключ утёк — отзовите его в кабинете, он перестанет работать сразу.

## Права

| Право | Что даёт |
|---|---|
| `sites:read` | список и карточка сайта, статус подключения |
| `sites:write` | добавление сайта, режим и настройки |
| `rules:read` | правила, превью правила, подсказки правил |
| `rules:write` | создание, изменение, удаление и перестановка правил, принятие и отклонение подсказок |
| `traffic:read` | посетители, выгрузка, аналитика, атаки, WAF |
| `dns:read` | зона, DNS-записи, рекомендации |
| `dns:write` | создание, изменение и удаление DNS-записей |
| `cache:purge` | сброс кеша сайта |

Метод `GET /me` доступен любому ключу. Какое право нужно каждому методу — в [Справочнике](https://bothunt.ru/docs/api/spravochnik). Без нужного права API отвечает `403` с кодом `insufficient_scope`, а в поле `required` перечислены права, которые нужны методу.

В мастере создания ключа есть пресеты: «Только чтение» — все права `:read`, «Полный доступ» — все права, «Свой набор» — права по одному.

## Сайты ключа

- **Все сайты** — ключ видит все сайты аккаунта, включая добавленные позже. Только такой ключ может добавить сайт.
- **Выбранные сайты** — ключ видит только отмеченные. Остальных сайтов для него нет: запрос к ним вернёт `404 site_not_found`, как к чужому сайту.

## Срок и IP-адреса

Срок — бессрочно, 30, 90 или 365 дней или своя дата. После срока ключ получает `401 api_key_expired`.

Список IP — до 20 адресов или подсетей IPv4 и IPv6, например `203.0.113.10` или `2001:db8::/32`. Запрос с другого адреса получит `403 api_key_ip_denied`. Пустой список — без ограничения.

## Отзыв и журнал

«Отозвать» в таблице ключей выключает ключ сразу и навсегда: следующий запрос получит `401 api_key_revoked`.

Вкладка «Журнал» показывает каждое изменение через API, которое дошло до выполнения: каким ключом, когда, с какого IP, что сделано и с каким результатом — включая ошибку самого выполнения (например, правило не найдено). Отказ на входе — нет нужного права, сайт не ваш, превышен лимит, неверные параметры — в журнал не попадает: такой запрос до выполнения не дошёл. Чтения в журнал не пишутся: для них в таблице ключей видно время и IP последнего использования. Журнал хранится 90 дней.

## Частые вопросы

**Потерял ключ — можно посмотреть его ещё раз?**

Нет. Ключ показывается один раз, у нас хранится только его хеш. Создайте новый ключ, перенесите его в свои сервисы и отзовите старый.

**Что будет с ключом, если удалить сайт?**

Сайт пропадёт из списка сайтов ключа. Ключ, у которого не осталось ни одного сайта, продолжит работать, но не увидит ни одного сайта — в кабинете рядом с ним будет предупреждение.

**Сколько ключей можно создать?**

До 20 действующих ключей на аккаунт. Отозванные и истёкшие в лимит не входят.
