# Ключі API — як створити і обмежити

> Як створити ключ API в кабінеті ZRAZU, вибрати права, домени, IP-адреси і строк, а також відкликати ключ, якщо він потрапив не в ті руки.

URL: https://zrazu.com/docs/api-keys/

Ключ API — це пароль для програми. Він дозволяє лише те, що ви вибрали: окремі дії з окремими доменами. Ключ ніколи не сильніший за людину, яка його випустила, і перевіряється при кожному виклику.

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

## Створити ключ

1. Відкрийте [кабінет](https://vse.zrazu.com/team/api-keys/) → «Команда» → «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. У рядку ключа натисніть «Відкликати» і підтвердіть: «Так, відкликати».

Ключ перестає працювати одразу. Якщо підозрюєте витік і не знаєте, який ключ, натисніть «Відкликати всі»: усі діючі ключі організації (для техніка — ваші особисті) зупиняться негайно. Потрібне підтвердження входу.

## Перевірити, що ключ працює

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

Відповідь покаже права, домени, дозволені IP і строк дії ключа. Подробиці про виклики — в [огляді API](https://zrazu.com/docs/api-overview.md).

## Якщо не вийшло

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