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

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

URL: https://zrazu.com/ru/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/ru/docs/api-overview.md).

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

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