API и MCP

Ключи API — как создать и ограничить

Как создать ключ API в кабинете ZRAZU, выбрать права, домены, IP-адреса и срок, а также отозвать ключ, если он попал не в те руки.

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

Ключи видят владелец, администратор и техник организации.

Создать ключ

  1. Откройте кабинет → «Команда» → «API-ключи».
  2. Нажмите «Новый ключ».
  3. Шаг «Шаблон»: выберите готовый набор («Только чтение», «Мониторинг», «Сертификаты SSL», «Зоны DNS — для менеджера», «Зоны DNS — полный доступ») или «Свой набор».
  4. Шаг «Права»: при необходимости измените, что именно разрешить.
  5. Шаг «Домены»: «Все домены организации, включая будущие» или «Только выбранные» (до 100 доменов).
  6. Шаг «Условия»: название, чей ключ, разрешённые IP-адреса, срок действия.
  7. Шаг «Итог»: проверьте, что ключ сможет, и нажмите «Подтвердить вход и выпустить».
  8. Скопируйте ключ кнопкой «Копировать» и сохраните в менеджере паролей или секретах вашего сервиса. Нажмите «Я скопировал(-а) ключ».

Ключ показывается один раз. Мы храним только его отпечаток и не можем показать ключ вторично. Потеряли — отзовите и выпустите новый.

Ключ выглядит так: zr_live_… и дальше длинная строка. Никогда не вставляйте его в чаты, письма или код страниц сайта.

Права

Права называются по схеме «что.действие». Класс показывает худшее последствие: 0 — чтение, 1 — обратимые изменения, 2 — деньги.

ПравоЧто разрешаетКласс
domain.readчитать домены, сроки и замки — без контактов0
monitor.readчитать состояние мониторинга0
monitor.editставить и снимать домены с мониторинга1
dns.readчитать зоны DNS и их записи0
dns.editменять записи зон и проверять делегирование — с письмом и журналом1
dns.zone_createдобавлять новые зоны — только ключ на все зоны1
keys.zones_grantдобавлять и убирать зоны в других ключах организации — права и срок не меняет1
ssl.readчитать сертификаты и скачивать их файлы0
ssl.reissueперевыпускать сертификат с новым ключом в пределах оплаченного срока1
ssl.orderзаказывать сертификаты с баланса организации2
billing.readвидеть баланс организации — без счетов и платежей0

Права dns.zone_create и keys.zones_grant действуют только для ключа на все домены и зоны организации.

Ключ не может больше, чем ваша роль в организации: если роль этого не даёт, право в кабинете недоступно.

Чего ключ не сможет никогда

Регистрировать и продлевать домены, менять контакты и замки, получать код переноса, отзывать сертификаты. Также ключ не управляет людьми и ключами, способами оплаты, вторым фактором и почтой входа, не удаляет аккаунт. Эти действия есть только в кабинете.

Условия ключа

  • Название — для вас, чтобы отличить ключ в списке; до 80 символов.
  • Чей ключ. «Личный» перестанет работать, если вас уберут из организации. «Организации» — для CI и интеграций, переживёт смену людей.
  • Разрешённые IP-адреса — один адрес или сеть (CIDR) на строку, до 20. Ключ будет работать только с них. Для ключа с правом ssl.order список адресов обязателен: такой ключ тратит деньги.
  • Срок действия. Для класса 0 по умолчанию и максимум — 365 дней. Для класса 1 по умолчанию 90 дней, максимум 365. Для класса 2 (деньги) по умолчанию 30 дней, максимум 90.
  • «Изменения — только с моим подтверждением». Ключ будет предлагать изменение планом, а применять будете вы — в «Планах». Для SSL и зон DNS эта опция пока недоступна.

Ключ, который 90 дней никто не вызывал, отключается сам: забытый ключ в старом репозитории — самый частый источник утечки.

Отозвать ключ

  1. Откройте «Команда» → «API-ключи».
  2. В строке ключа нажмите «Отозвать» и подтвердите: «Да, отозвать».

Ключ перестаёт работать сразу. Если подозреваете утечку и не знаете, какой ключ, нажмите «Отозвать все»: все действующие ключи организации (у техника — ваши личные) остановятся немедленно. Нужно подтверждение входа.

Проверить, что ключ работает

curl -H "Authorization: Bearer zr_live_..." https://api.zrazu.com/v1/api-keys/current

Ответ покажет права, домены, разрешённые IP и срок действия ключа. Подробности о вызовах — в обзоре API.

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

  • Нет пункта «API-ключи». Ключи видят владелец, администратор и техник. Попросите владельца организации изменить роль или выпустить ключ.
  • Право неактивно и подписано «ваша роль этого не даёт». Ключ не может иметь права, которого нет у вашей роли.
  • Кнопка выпуска просит подтвердить вход. Это защита: выпуск ключа требует повторного подтверждения входа.
  • Слишком много ключей. В организации может быть до 50 действующих ключей и до 20 новых в сутки; отзовите ненужные.
  • Ключ отвечает `401 key_expired` или `key_idle`. Срок истёк или ключ 90 дней не вызывали — выпустите новый.

Эта страница в Markdown