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