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

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

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

Открыть «API» в кабинете

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

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

Права

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

Метод GET /me доступен любому ключу. Какое право нужно каждому методу — в Справочнике. Без нужного права 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 действующих ключей на аккаунт. Отозванные и истёкшие в лимит не входят.

Обновлено

Не нашли ответ?

Напишите в поддержку из кабинета — укажите сайт и что видите на экране, ответим по вашему случаю.

Написать в поддержку