Cloudflare: API токен и Global API Key

Коротко

Для автоматизации берите API токен с минимальными правами. Global API Key открывает доступ ко всему аккаунту.
Токен для управления DNS: права Zone, DNS, Edit и ограничение одной зоной.
Токен передают в заголовке Authorization: Bearer, а Global API Key в паре X-Auth-Email и X-Auth-Key.
Если ключ утёк, сразу обновите или удалите токен, смените Global key и проверьте Audit Logs.
Ключи не отправляют в чаты и не показывают на скриншотах.

Чем они отличаются

API токен. Его можно ограничить по правам (например, только DNS), по зонам, по IP-адресам и по сроку действия. Токенов можно создать несколько под разные задачи и отозвать любой, не затронув остальные.
Global API Key. Это устаревший способ: ключ один на пользователя, и, по документации Cloudflare, он имеет те же права, что и сам пользователь. Ограничить его нельзя. Cloudflare не рекомендует его новым клиентам и советует переходить на токены.

Где что создаётся

Токен:

В панели откройте My Profile, API Tokens и нажмите Create Token.
Выберите шаблон Edit zone DNS или задайте права вручную.
В Permissions укажите Zone, DNS, Edit.
В Zone Resources выберите Include, Specific zone и нужный домен.
При желании задайте ограничение по IP и срок действия.
Создайте токен и сразу сохраните его: значение показывается один раз.

Токены уровня аккаунта (Manage Account, Account API Tokens) не привязаны к конкретному человеку и лучше подходят для сервисов, если инструмент их поддерживает. Проверяются они другим запросом, он показан ниже.

Global API Key находится в My Profile, API Tokens, в блоке API Keys, кнопка View. Открывайте его, только если инструмент не умеет работать с токенами.

Какие права нужны для DNS

Обычно достаточно Zone, DNS, Edit для одной зоны. Некоторые инструменты дополнительно просят Zone, Zone, Read, чтобы найти зону по имени. Об этом написано в их инструкции. Не добавляйте права на всякий случай и не выбирайте All zones без причины.

Как выглядят запросы

Вместо реальных значений здесь стоят заглушки в угловых скобках.

# API токен
curl "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/dns_records" \
  --header "Authorization: Bearer <API_TOKEN>"

# Global API Key
curl "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/dns_records" \
  --header "X-Auth-Email: <EMAIL>" \
  --header "X-Auth-Key: <GLOBAL_API_KEY>"

# проверка обычного токена
curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  --header "Authorization: Bearer <API_TOKEN>"

# проверка токена уровня аккаунта
curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/tokens/verify" \
  --header "Authorization: Bearer <API_TOKEN>"

Zone ID и Account ID

Домен должен быть уже подключён к Cloudflare. Как это сделать, описано в статье как подключить домен к Cloudflare. Zone ID найдёте так: откройте домен, страница Overview, блок API ближе к низу страницы. Там же указан Account ID. Это идентификаторы, а не пароли: доступа они сами по себе не дают, но публиковать их без нужды не стоит.

Почему инструмент с Global key рискован

Сервис, которому вы отдали Global API Key, получает те же права, что и вы: может менять DNS всех доменов, удалять зоны и менять настройки аккаунта. Если сервис взломают или ключ утечёт, пострадает весь аккаунт, а не один домен.

Как решить:

Инструмент поддерживает токены: создайте токен с минимальными правами.
Работает только с Global key, как некоторые старые скрипты и панели: поищите обновление или замену. Если без него не обойтись, заведите отдельного пользователя Cloudflare с ограниченной ролью. По документации, ключ повторяет права пользователя, значит, у такого пользователя он тоже будет ограничен.
Не передавайте ключи людям и сервисам, которым не доверяете полностью.

Если ключ утёк

Токен: My Profile, API Tokens, три точки рядом с токеном, Roll и подтверждение. Старое значение перестанет работать. Можно и просто удалить токен.
Global API Key: в блоке API Keys нажмите Change.
Откройте Manage Account, Audit Logs и посмотрите, что менялось за нужный период, кем и откуда. Лишние изменения отмените.
Смените пароль, завершите чужие сессии и проверьте, что включена двухфакторная защита.
Впишите новое значение в свои инструменты. Найдите, где ключ утёк (git, чат, скриншот, лог), и удалите его там. Само по себе удаление сообщения ключ не защищает, поэтому первые два шага обязательны.

Где хранить и чего не делать

Храните ключи в переменных окружения или менеджере секретов, а файлы с ними закрывайте правами chmod 600. Не отправляйте ключи в чаты, не коммитьте их в git и не показывайте на скриншотах и записях экрана. Если нужно показать ошибку, закройте значения.

Если не получилось

Ошибка авторизации: токен скопирован с пробелом или не полностью, либо его уже обновили. Проверьте его запросом verify из примера выше (для токена уровня аккаунта нужен адрес с Account ID).
Ошибка доступа к зоне: в Zone Resources выбрана другая зона или не хватает права DNS, Edit.
Запрос с Global key отклонён: проверьте email аккаунта в X-Auth-Email и то, что ключ не меняли.
Токен с ограничением по IP не работает: запрос идёт с другого адреса, проверьте список разрешённых IP.