Токены API Kapsule Orbit и REST API

API tokens let a script, a CI pipeline or your own tooling drive Orbit without a browser session: trigger deployments, report CI check results, download build artifacts, manage cron jobs and more…

Токены API позволяют скрипту, CI конвейеру или собственным инструментам управлять Kapsule Orbit без сеанса браузера: запускать развёртывания, сообщать результаты CI проверок, загружать артефакты сборки, управлять заданиями cron и многое другое, всё с аутентификацией Bearer токена, область действия которого вы определяете сами.

Где находятся токены

Откройте Orbit и выберите Tokens в навигации верхнего уровня. Страница озаглавлена API Access Tokens и сразу формулирует своё правило: токены отображаются один раз при создании.

Полная документация endpoint находится в одном клике. Карточка API Reference содержит кнопку View docs, которая открывает встроенный справочник для каждого endpoint Orbit.

API Access Tokens page in Orbit

Создание токена

Нажмите New token.
Дайте ему Token name. Назовите его в честь того, что его будет использовать, например имя CI workflow, чтобы инвентарь было легче читать позже.
Выберите его Scopes.
При необходимости установите Expiry. Оставьте пустым для токена, который не истекает.
Нажмите Create token.

Необработанный токен отображается один раз под заголовком One-time reveal с кнопкой копирования. Вставьте его прямо в хранилище секретов CI. Нет способа увидеть его снова: хранится только хеш SHA-256 токена, поэтому даже KapsuleHost не сможет его восстановить.

Аккаунт может содержать до 20 активных токенов. Создание двадцать первого отклоняется с сообщением о необходимости сначала отозвать существующий.

Никогда не вставляйте токен в сообщение чата, тикет, коммит или скриншот. Токен с deploy:write может отправить код в production, а токен с env:write может читать и заменять конфигурацию вашего окружения. Относитесь к нему ровно так же, как к паролю.

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

Области действия (Scopes) это весь смысл токенов: каждый несёт только те разрешения, которые вы ему дали.

Scope	Предоставляет
`deploy:write`	Запуск и управление развёртываниями
`project:read`	Чтение деталей проекта и окружения
`project:write`	Изменение параметров проекта
`env:read`	Чтение метаданных переменных окружения
`env:write`	Установка и удаление переменных окружения

Новый токен по умолчанию имеет deploy:write и project:read, что необходимо конвейеру развёртывания и больше ничему.

Предоставьте минимальный набор, необходимый для работы. Токен, которому требуется только сообщить результат CI, не нуждается в project:write. Скрипту мониторинга, работающему только для чтения, не нужна область записи. Каждый endpoint в справочнике указывает минимальную требуемую область.

Использование токена

Аутентификация происходит через заголовок Bearer для базового API https://kapsulehost.com:

curl -X POST https://kapsulehost.com/api/orbit/$ORBIT_PROJECT_ID/deployments \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main"}'

Страница Tokens содержит готовый фрагмент CI/CD usage и starter workflow GitHub Actions. Starter сохраняется как .github/workflows/orbit-deploy.yml и требует два секрета репозитория: ORBIT_TOKEN и ORBIT_PROJECT_ID. Копируйте оба со страницы вместо того, чтобы переписывать их.

Что охватывает API

Встроенный справочник документирует каждую область с её параметрами и требуемой областью действия:

Deployments: запуск развёртывания, опционально на именованной ветке, опционально запланированное на будущее время между пятью минутами и тридцатью днями вперёд, с заметкой до 500 символов. Листинг поддерживает нечёткий поиск по коммиту, сообщению, ветке и автору, плюс фильтры по ветке, статусу и окружению, с курсорной пагинацией до 100 результатов на странице.
Deployment checks: регистрация качественного контроля в начале CI задачи, затем отчёт о результате по завершении. Проверка required, которая не пройдена, переводит развёртывание в FAILED и откатывает окружение к предыдущему успешному развёртыванию, это то, как ваш собственный набор тестов становится настоящим шлюзом развёртывания.
Branch protection: правила с шаблонами glob, которые блокируют автоматические развёртывания до прохождения требуемых проверок и, опционально, утверждения кем-либо. До десяти правил на проект.
Build artifacts: получить предподписанный URL загрузки скомпилированного вывода успешного развёртывания. URL действителен пятнадцать минут.
Project transfer: инициировать, отменить и проверить статус передачи на другой аккаунт. См. раздел Transferring an Orbit Project.
Cron jobs: листинг, создание, обновление, удаление, запуск и чтение истории выполнения. См. раздел Orbit Cron Jobs.
Timeline annotations: создание и управление аннотациями инцидента, релиза, вехи, заметки и флага. См. раздел Orbit Timeline Annotations.
Status page: чтение и запись конфигурации общедоступной страницы статуса. См. раздел Orbit Status Page.
Edge functions: листинг, создание, обновление и развёртывание обработчиков edge. См. раздел Orbit Edge Functions.

Аутентификация сеанса из панели работает наряду с Bearer токенами, поэтому endpoint, который вы можете вызвать из браузера, обычно можно вызвать и из скрипта.

Turbo Remote Cache

Страница Tokens также содержит карточку Remote Build Cache. Она реализует Turborepo Remote Cache Protocol, позволяя monorepo обмениваться кешами сборок между CI запусками и машинами разработчиков.

Включите её на карточке, скопируйте сгенерированный токен и установите его вместе с ID аккаунта как TURBO_TEAM в окружении CI. Артефакты до 150 МБ каждый принимаются. Карточка также предлагает Rotate token и Disable.

Если CI вашего monorepo тратит большую часть времени на пересборку пакетов, которые не изменились, это единственная наиболее ценная вещь на этой странице.

Управление инвентарём

Token inventory перечисляет каждый активный токен с информацией:

Когда он был Created.
Когда он был Last used, или Never.
Когда он Expires, с бейджем expired после истечения.

Колонка Last used это та, которую нужно проверить. Токен, который никогда не использовался, либо неправильно настроен, либо забыт, и в обоих случаях это учётные данные, лежащие без дела. Подсказка самой страницы говорит это ясно: отозовите всё, что вы не узнаёте.

Отзыв токена

Нажмите управление отзыва в строке. Подтверждение явное: всё аутентифицирующееся с этим токеном немедленно теряет доступ, и это невозможно отменить.

Отзовите токен, когда конвейер снят с производства, когда кто-то с доступом к вашим CI секретам уходит, или в момент, когда вы подозреваете утечку токена. Нет частичного отзыва и периода благодати, что ровно то, что вам нужно в случае утечки.

Установите срок действия на токены, которые вы создаёте для разовой работы. Истекающий токен самоудаляется; постоянный токен, созданный для двухдневной миграции, всё ещё действителен два года спустя.

Поиск и устранение неисправностей

401 Unauthorized. Заголовок неправильный или токен был отозван или истёк. Проверьте, что заголовок это Authorization: Bearer <token> с одним пробелом, и что ваш CI секрет не имеет замыкающего символа новой строки.

403 Forbidden. Токен действителен, но ему не хватает области для этого endpoint. Справочник перечисляет минимальную область на endpoint. Области фиксируются при создании, поэтому создайте новый токен с правильным набором.

429 on creation. Вы достигли лимита двадцати токенов. Отзовите что-либо из инвентаря.

The artifact URL stops working. Предподписанные URL действуют пятнадцать минут. Запросите свежий вместо сохранения URL.

A scheduled deployment is rejected. Запланированное время должно быть между пятью минутами и тридцатью днями в будущем.

Что дальше

Deploying Your Project чтобы узнать, что именно делает запущенное развёртывание.
Orbit Deployment Pipeline чтобы увидеть, какие шлюзы пройдут ваши API развёртывания.
Orbit Plan Limits чтобы узнать, что включает ваш план.