# API ключи и доступ разработчика

Source: https://support.kapsulehost.com/ru-ru/developer-api-access

KapsuleHost предоставляет вам две поверхности разработчика: ограниченные API-ключи для программного чтения вашего аккаунта и удаленный кэш сборок, который ускоряет сборки Turborepo и Nx на ваших машинах и CI-раннерах.

По умолчанию ни один из них не включен. Оба создаются из раздела **Параметры**, и оба предоставляют вам секрет ровно один раз.

## Создание API-ключа

API-ключи находятся в разделе **Параметры**, затем **Безопасность**, в карточке **API ключи**.

![Карточка API ключи в параметрах безопасности KPanel с видимыми чипами области действия](https://support.kapsulehost.com/help/screenshots/developer-api-access.8d15f634.webp)

1. Перейдите в раздел **Параметры**, затем **Безопасность**.
2. Прокрутите до **API ключи** и нажмите **Новый ключ**.
3. Дайте ключу имя. Поле предлагает "Имя ключа (например, Мой скрипт автоматизации)". Имя предназначено только для вас, поэтому укажите, где будет использоваться ключ.
4. Нажимайте на чипы области действия, чтобы выбрать, что может делать ключ. Три области для чтения предварительно выбраны: `read:sites`, `read:email` и `read:domains`. Нажимайте на чип, чтобы добавить или удалить его.
5. Нажмите **Создать**.

Полный ключ появляется один раз в зеленой панели с заголовком "Копировать сейчас". Скопируйте его прямо в ваше хранилище секретов. Когда вы закроете эту панель, ключ исчезнет: сохраняется только короткий префикс, который список когда-либо может вам снова показать.

> **Warning:** Ключ никогда не отображается второй раз и не может быть восстановлен. Если вы его потеряете, отозвите этот ключ и создайте новый. Не вставляйте его в общий документ, задачу, коммит или сообщение в чате.

Только роли **Владелец** и **Администратор** могут создавать ключ. Любая другая роль получает ошибку прав доступа. Когда создается ключ, предупреждение безопасности отправляется на адрес того, кто его создал, поэтому неожиданное письмо стоит немедленно проверить.

## Области действия

Предлагаются семь областей действия:

| Область действия | Предоставляет |
|---|---|
| `read:sites` | Чтение ваших веб-сайтов |
| `write:sites` | Зарезервировано для операций записи на веб-сайты |
| `read:email` | Чтение ваших почтовых ящиков |
| `write:email` | Зарезервировано для операций записи на почтовые ящики |
| `read:domains` | Чтение ваших доменов |
| `write:domains` | Зарезервировано для операций записи на домены |
| `read:billing` | Зарезервировано для чтения данных биллинга |

> **Note:** Сегодня API клиента предназначен только для чтения. Области действия `write:` и `read:billing` можно выбрать на ключе, но в данный момент ни одна конечная точка клиента их не использует, поэтому их предоставление ничего не меняет. Предоставляйте только те области для чтения, которые вам действительно нужны, и пересмотрите ключ, когда будут доступны конечные точки записи.

## Использование ключа

Отправляйте ключ в качестве токена-носителя на заголовок `Authorization`.

```sh
curl https://kpanel.kapsulehost.com/api/v1/sites \
  -H "Authorization: Bearer YOUR_KEY_HERE"
```

Три конечные точки принимают API-ключ клиента:

| Конечная точка | Требуемая область действия | Возвращает |
|---|---|---|
| `GET /api/v1/sites` | `read:sites` | Ваши веб-сайты с доменом, типом приложения и статусом |
| `GET /api/v1/domains` | `read:domains` | Ваши домены со статусом и датой истечения |
| `GET /api/v1/mailboxes` | `read:email` | Ваши почтовые ящики |

Запрос без ключа, с неизвестным ключом или отозванным ключом возвращает `401`. Действительный ключ без правильной области действия возвращает `403` с сообщением, называющим требуемую область действия. Каждый успешный вызов обновляет временную метку последнего использования ключа.

> **Tip:** Опрашивайте осторожно. Эти конечные точки читают живые данные аккаунта, и плотный цикл против них неотличим от злоупотребления. Один раз в минуту достаточно для всего, что нужно панели инструментов; один раз в час обычно более чем достаточно.

## Просмотр и отзыв ключей

Таблица API ключи перечисляет каждый активный ключ по **Имени**, **Префиксу** (видимому началу ключа) и **Областям действия**. Нажмите **Отозвать** в конце строки, чтобы его отключить.

> **Important:** Отзыв вступает в силу немедленно и диалога подтверждения нет. Следующий запрос с использованием этого ключа завершается неудачей с `401`. Отозванный ключ не может быть восстановлен, поэтому убедитесь, что вы знаете, что его использует, прежде чем нажимать.

Ключи принадлежат **аккаунту**, а не человеку, который их создал. Удаление коллеги со [страницы команды](https://support.kapsulehost.com/ru-ru/account-team-members) не отзывает созданные ими ключи. Включите проверку ключей в процесс исключения: удалите человека, затем зайдите сюда и отозовите все, что они создали.

Создание и отзыв ключей записываются в [журнале аудита](https://support.kapsulehost.com/ru-ru/account-audit-log) под действиями `api_key.*` с указанием субъекта и исходящего IP-адреса.

## Удаленный кэш сборок

Страница **Разработчик** в группе "Дополнительно" боковой панели параметров предлагает **Удаленный кэш сборок**. На панели описано это как способ "Ускорить сборки Turborepo и Nx путем совместного использования распределенного кэша на машинах и конвейерах CI".

1. Перейдите в раздел **Параметры**, затем **Разработчик**.
2. Нажмите **Включить удаленный кэш**.
3. Скопируйте токен из панели с заголовком "Новый токен создан. Скопируйте его сейчас, он больше не будет показан".

Затем установите две переменные окружения в конфигурации CI или локальный `.env.local`:

```sh
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
```

ID команды - это ваш ID аккаунта KapsuleHost, показанный в инструкциях по установке на той же странице.

На странице указана собственная совместимость: Turborepo 1.x и позже, Nx 16 и позже, а также любой инструмент, реализующий тот же протокол удаленного кэша. Артефакты хранятся на аккаунт и никогда не совместно используются между аккаунтами.

На карточке находятся два дополнительных элемента управления:

- **Ротировать токен** выпускает новый токен и делает недействительным старый. Любое задание CI, все еще содержащее старый токен, прекращает использование кэша, поэтому ротируйте и обновляйте ваши секреты вместе.
- **Отключить** полностью отключает кэш.

## Выбор между двумя

Они решают несвязанные проблемы и не являются взаимозаменяемыми.

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

Используйте **удаленный кэш сборок**, когда ваши сборки идут медленно, потому что каждая машина и каждый запуск CI перестраивает одни и те же неизменные пакеты. Это не имеет ничего общего с размещенными сайтами и не читает данные вашего аккаунта.

## Устранение неполадок

**Каждый запрос возвращает 401.** Подтвердите, что вы отправили заголовок как `Authorization: Bearer <key>` с одним пробелом, что ключ не был усечен при копировании и что он не был отозван. Сравните начало вашего ключа со столбцом **Префикс**, чтобы убедиться, что вы используете тот ключ, который думаете.

**Запрос возвращает 403, называя область действия.** Ключ не содержит эту область действия. Области действия фиксируются при создании ключа, поэтому создайте замену с правильными областями действия и отозовите старую.

**Я не вижу карточку API ключи.** Она находится на странице "Безопасность", а не на странице "Разработчик". Страница "Разработчик" содержит только кэш сборок.

**Кнопка "Новый ключ" ничего не делает.** Ваша роль ниже администратора. Попросите владельца или администратора.

**Сборки не попадают в кэш.** Проверьте, что оба `TURBO_TOKEN` и `TURBO_TEAM` присутствуют в окружении сборки, что токен не был ротирован с момента его установки, и что страница по-прежнему показывает значок **Active**.

**Появился ключ, который я не создавал.** Считайте это компрометацией. Отозовите его, затем выполните инструкции из [Account Security](https://support.kapsulehost.com/ru-ru/account-security) и проверьте [журнал аудита](https://support.kapsulehost.com/ru-ru/account-audit-log) на предмет того, что еще изменилось.