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