API і ключі доступу

Ключ — це набір політик

Права та ресурси — різні осі: «редагувати DNS» і «в яких доменах» не склеюються в одне. Умови (IP, строк дії, ліміт витрат) діють на весь ключ.

Ключ
 ├─ середовище: live · test
 ├─ політика: право [dns.edit] на ресурси [домени з міткою «клієнт-А»]
 ├─ політика: право [domain.renew] на ресурси [example.com.ua]
 └─ умови: IP 203.0.113.0/24 · до 2026-12-26 · витрати ≤ 2 000 ₴/міс

Чотири класи небезпеки

Клас визначає строк життя ключа, обов’язковість обмеження за IP і те, хто підтверджує операцію.

Каталог прав (фрагмент)

Повний каталог — у документації; тут — найчастіші права з класом небезпеки праворуч.

domain.read

список доменів, терміни, статуси

0

domain.renew

продовжити домен — це витрата

2

domain.nameservers

змінити сервери імен; на живому домені гасить сайт і пошту на час TTL

3

dns.edit

створювати, змінювати, видаляти записи DNS через план з перевіркою

1

dns.acme_challenge

лише запис TXT у _acme-challenge.<імʼя> — для certbot і подібних

1

cert.issue

безкоштовний сертифікат Let’s Encrypt

1

monitor.read

перевірки, історія, звіти моніторингу

0

billing.topup

поповнити баланс зі збереженої картки

2

Право dns.acme_challenge навмисно вузьке: зламаний вебсервер із таким ключем може лише перевипустити сертифікат свого домену, а не переписати MX і забрати пошту.

Що ключу не видається ніколи

• Код перенесення домену — тільки людині в кабінеті після повторного входу.
• Зміна власника (реєстранта) домену.
• Керування людьми й ключами організації.
• Спосіб оплати, вимкнення двоетапної перевірки, видалення акаунта.

Приклад запиту

Кожен запис на запис вимагає Idempotency-Key: повтор повертає той самий результат, а не нову операцію.

GET /v1/domains/kava.com.ua HTTP/1.1
Authorization: Bearer zr_live_…
Idempotency-Key: 8f14e45f-…

200 OK
{ "domain": "kava.com.ua", "status": ["ok"],
  "expires_at": "2027-09-12", "auto_renew": true }

Помилка — машинний код плюс повідомлення людською мовою і запропоновані дії:

{ "error": {
  "code": "domain_taken",
  "message": { "uk": "kava.com.ua зайнятий до 2027-09-12.",
               "en": "kava.com.ua is registered until 2027-09-12." },
  "actions": [ { "type": "check_alternatives", "href": "/v1/search?q=kava" } ] } }

Де видати ключ

Ключі видаються в кабінеті: шаблон прав → домени → умови → підсумок людськими словами. Публічний read-only MCP доступний без ключа.

Часті питання