Аккаунт
API ключи и доступ для разработчиков
Kapsule gives you two developer surfaces: scoped API keys for reading your account programmatically, and a remote build cache that speeds up Turborepo and Nx builds on your own machines and CI…
KapsuleHost предоставляет две поверхности разработчика: ограниченные по объему ключи API для программного доступа к данным вашего аккаунта и удаленный кэш сборки, который ускоряет сборки Turborepo и Nx на ваших собственных машинах и CI-запускателях.
Ни одна из них не включена по умолчанию. Обе создаются из Параметров, и обе выдают вам секрет ровно один раз.
Создание ключа API
Ключи API находятся в Параметры, затем Безопасность, в карточке API Keys.
- Перейдите в Параметры, затем Безопасность.
- Прокрутите до API Keys и нажмите New key.
- Дайте ключу имя. Поле предлагает «Key name (e.g. My automation script)». Имя предназначено только для вас, поэтому указывайте, где будет использоваться ключ.
- Нажимайте на чипы объема, чтобы выбрать, что может делать ключ. Три области для чтения предварительно выбраны:
read:sites,read:emailиread:domains. Нажимайте на чип, чтобы добавить или удалить его. - Нажмите Create.
Полный ключ появляется один раз в зеленой панели с заголовком «Copy now». Скопируйте его прямо в хранилище секретов. Когда вы закроете эту панель, ключ исчезнет: сохранится только короткий префикс, который это всё, что список сможет показать вам снова.
Ключ никогда не отображается второй раз и не может быть восстановлен. Если вы потеряете его, отозовите этот ключ и создайте новый. Не вставляйте его в общий документ, тикет, коммит или сообщение в чате.
Только роли Owner и Admin могут создать ключ. Любая другая роль получает ошибку прав доступа. При создании ключа на адрес того, кто его создал, отправляется письмо оповещения об опасности, поэтому неожиданное письмо стоит немедленно расследовать.
Объемы доступа
Предлагаются семь объемов доступа:
| Объем доступа | Предоставляет |
|---|---|
read:sites | Чтение ваших веб-сайтов |
write:sites | Зарезервировано для операций записи на веб-сайты |
read:email | Чтение ваших почтовых ящиков |
write:email | Зарезервировано для операций записи на почтовые ящики |
read:domains | Чтение ваших доменов |
write:domains | Зарезервировано для операций записи на домены |
read:billing | Зарезервировано для чтения данных выставления счетов |
Клиентский API в настоящее время доступен только для чтения. Объемы доступа write: и read:billing можно выбрать на ключе, но ни одна конечная точка клиента их не использует, поэтому их предоставление ничего не меняет. Предоставляйте только те области для чтения, которые вам действительно нужны, и пересмотрите ключ, когда появятся конечные точки для записи.
Использование ключа
Отправляйте ключ как маркер носителя в заголовке Authorization.
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 с сообщением, в котором указывается требуемый объем доступа. При каждом успешном вызове обновляется отметка времени последнего использования ключа.
Опрашивайте без спешки. Эти конечные точки считывают данные живого аккаунта, и плотный цикл к ним неотличим от злоупотребления. Один раз в минуту щедро подходит для чего-либо, что требует панель управления; один раз в час обычно достаточно.
Просмотр и отзыв ключей
Таблица API Keys содержит список каждого активного ключа по Name, Prefix (видимому началу ключа) и Scopes. Нажмите Revoke в конце строки, чтобы его удалить.
Отзыв вступает в силу немедленно и нет диалога подтверждения. Следующий запрос с использованием этого ключа завершится ошибкой 401. Отозванный ключ не может быть восстановлен, поэтому убедитесь, что вы знаете, что его использует, прежде чем нажимать.
Ключи принадлежат аккаунту, а не лицу, которое их создало. Удаление товарища по команде со страницы Team не отзывает созданные им ключи. Включите просмотр ключей в ваш процесс увольнения: удалите человека, а затем придите сюда и отозовите всё, что они создали.
Создание и отзыв ключей записываются в журнал аудита под api_key.* действиями с указанием актора и исходящего IP-адреса.
Удаленный кэш сборки
На странице Developer, в группе Advanced панели параметров, предлагается Remote Build Cache. Панель описывает его как способ «Accelerate Turborepo and Nx builds by sharing a distributed cache across machines and CI pipelines».
- Перейдите в Параметры, затем Developer.
- Нажмите Enable remote cache.
- Скопируйте токен из панели с надписью «New token generated. Copy it now, it won't be shown again».
Затем установите две переменные окружения в конфигурации CI или локального .env.local:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
ID команды это ID вашего аккаунта KapsuleHost, показанный в инструкциях установки на той же странице.
На странице указана собственная совместимость: Turborepo 1.x и позже, Nx 16 и позже, а также любой инструмент, реализующий один и тот же протокол удаленного кэша. Артефакты хранятся для каждого аккаунта и никогда не используются совместно между аккаунтами.
Еще два элемента управления находятся на карточке:
- Rotate token выдает новый токен и делает недействительным старый. Любое задание CI, которое все еще хранит старый токен, перестает использовать кэш, поэтому ротируйте и обновляйте ваши секреты вместе.
- Disable полностью отключает кэш.
Выбор между двумя вариантами
Они решают несвязанные проблемы и не взаимозаменяемы.
Используйте API key, когда что-то вне KapsuleHost должно знать состояние вашего аккаунта: информационная доска со списком ваших сайтов, скрипт, который предупреждает вас об истечении сроков доменов, экспорт инвентаря.
Используйте remote build cache, когда ваши сборки медленные, потому что каждая машина и каждый запуск CI пересобирают одни и те же неизменные пакеты. Это не имеет ничего общего с размещенными сайтами и не считывает данные вашего аккаунта.
Если вы развертываете из Git вместо вызова API, вместо этого посмотрите на Kapsule Orbit. Он строит и отправляет непосредственно из вашего репозитория, с кэшированием сборки, обрабатываемым для вас.
Поиск и устранение неисправностей
Каждый запрос возвращает 401. Подтвердите, что вы отправили заголовок как Authorization: Bearer <key> с одним пробелом, что ключ не был обрезан при копировании и что он не был отозван. Сравните начало вашего ключа со столбцом Prefix, чтобы убедиться, что вы используете тот ключ, который вы думаете.
Запрос возвращает 403 с указанием объема доступа. Ключ не несет этого объема доступа. Объемы доступа фиксированы при создании ключа, поэтому создайте замену с нужными объемами доступа и отозовите старый.
Я не вижу карточку API Keys. Она находится на странице Security, а не на странице Developer. На странице Developer находится только кэш сборки.
Кнопка New key ничего не делает. Ваша роль ниже Admin. Попросите Owner или Admin.
Сборки не попадают в кэш. Проверьте, что оба TURBO_TOKEN и TURBO_TEAM присутствуют в окружении сборки, что токен не был ротирован с момента его установки, и что на странице все еще показан значок Active.
Появился ключ, который я не создавал. Относитесь к нему как к компрометации. Отозовите его, затем пройдитесь по Account Security и проверьте журнал аудита, чтобы узнать, что еще изменилось.