Создание, использование и ротация API-ключей Triggo для агентных интеграций.

API-ключи

Каждый вызов runtime REST API (/api/v1/runtime/*) и эндпоинта MCP (POST /mcp) аутентифицируется Bearer API-ключом. Эта страница описывает полный жизненный цикл: создание, права доступа, использование, ротацию, отзыв и операционную гигиену.

Ключи всегда привязаны к рабочему пространству. Они наследуют его тарифный план для лимитов и квот и несут явный набор прав доступа (scopes), определяющих, что ими можно вызывать.

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

Ключи создаются в разделе Agent Setup веб-приложения Triggo по адресу /agent-setup. Откройте панель API Keys, нажмите Create, задайте ключу понятное имя (по одному на интеграцию — claude-desktop, ci-pipeline, zapier-bridge и т. п.), выберите нужные права доступа и при желании задайте дату истечения.

Ключи имеют формат trg_<24 случайных байта, base64url>. Префикс trg_ плюс первые четыре символа случайной части образуют 8-символьный публичный префикс, который хранится в открытом виде и отображается в UI для последующей идентификации (например, trg_AbCd****).

Открытый ключ показывается ровно один раз — в момент создания. Triggo его не хранит. Сервер сохраняет только солёный хеш SHA-256 (sha256(salt + rawKey), с уникальной 16-байтной случайной солью на ключ) и 8-символьный префикс. Если вы потеряете открытый ключ, придётся провести ротацию — путь восстановления отсутствует. Сразу скопируйте ключ в ваше секрет-хранилище.

Количество активных ключей на рабочее пространство ограничено тарифом: бесплатный — 1, starter — 3, pro — 10, business — без ограничений. Отозванные ключи в квоту не засчитываются.

Права доступа (scopes)

Каждый API-ключ несёт явный список прав доступа. Сервер проверяет их и на runtime REST, и на инструментах MCP — если эндпоинт или инструмент требует actions:run, ключ с одним только actions:read получит HTTP 403.

Канонический набор прав:

Право	Доступ к
`actions:read`	Просмотр опубликованных действий: `GET /actions`, `GET /actions/:slug` и инструменты MCP `list_actions`, `get_action`.
`actions:run`	Запуск опубликованных действий: `POST /actions/:slug/run` и инструмент MCP `run_action`.
`runs:read`	Чтение статуса и истории запусков: `GET /runs`, `GET /runs/:runId` и инструменты MCP `get_run_status`, `list_runs`. Также требуется для повтора запуска.
`approvals:decide`	Подтверждение или отклонение ожидающих запусков: `POST /runs/:runId/approve` и инструмент MCP `approve_run`.
`connectors:read`	Просмотр коннекторов и их операций и схем: инструменты MCP `list_connectors`, `get_connector_operations`, `get_operation_schema`, `get_build_status`.
`connectors:write`	Сборка и валидация пользовательских коннекторов: инструменты MCP `build_connector`, `validate_connector`.
`workflows:read`	Просмотр workflow: инструменты MCP `list_workflows`, `get_workflow`, `open_workflow`.
`workflows:write`	Создание, переименование, удаление и публикация workflow: инструменты MCP `create_workflow`, `update_workflow`, `delete_workflow`, `deploy_workflow`.
`workflows:run`	Зарезервировано для runtime-эндпоинтов запуска workflow. Каноническое и назначаемое, но ни один инструмент MCP его сейчас не требует.

Если при создании ключа поле scopes не указано, по умолчанию назначаются actions:read, actions:run, runs:read, connectors:read, workflows:read, workflows:write — этого достаточно, чтобы типичный агент находил и запускал опубликованные действия, читал результаты и управлял workflow. Придерживайтесь принципа наименьших привилегий: не добавляйте approvals:decide, connectors:write или workflows:run, если интеграции это не требуется.

Все девять прав выше — канонические и назначаемые на API-ключи сегодня: больше нет расхождения между требованиями инструментов MCP и тем, что может запросить Bearer API-ключ.

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

Отправляйте открытый ключ в заголовке Authorization: Bearer … при каждом запросе к runtime. Ни кук, ни X-API-Key, ни query-параметров.

curl -sS https://api.triggo.ai/api/v1/runtime/actions \
  -H "Authorization: Bearer trg_YOUR_API_KEY" \
  -H "Accept: application/json"

При успехе вы получаете список действий и заголовки лимитов (x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset). При ошибке — структурированное тело ошибки, а при превышении лимита — заголовок retry-after в секундах. Эндпоинт MCP (POST /mcp) использует тот же Bearer-заголовок — детали транспорта см. в быстром старте MCP.

Ротация

Проводите ротацию по расписанию (раз в квартал — разумная отправная точка), а также при смене владельца интеграции, потере ноутбука или по требованию политики секрет-хранилища. Шаблон — без простоя:

Создайте новый ключ с теми же правами, что и у старого.
Разверните новый ключ у всех вызывающих и убедитесь, что запросы с ним проходят (проверьте логи, поле lastUsedAt).
Отзовите старый ключ.

Во время окна перекрытия оба ключа активны, поэтому ни один запрос не увидит разрыв. Triggo также предлагает ротацию в один клик в UI: она атомарно создаёт ключ-замену с тем же именем, правами и сроком, после чего отзывает оригинал. Если ваш деплой не атомарен, используйте ручной трёхшаговый процесс — так вы контролируете перекрытие.

Отзыв

Ключ отзывается в панели Agent Setup. Отзыв ставит isActive = false и метку revokedAt; следующий вызов validateKey() от любого клиента вернёт 401 Unauthorized с сообщением "API key revoked". Отменить отзыв нельзя — если нужно восстановить доступ, создайте новый ключ.

Идущие запуски не отменяются. Запуск, начатый под теперь отозванным ключом, доходит до конца в исполнителе — ключ контролирует только входящие HTTP/MCP-вызовы, а не фоновое выполнение. Сразу перестаёт работать только дальнейший опрос статуса, подтверждения и повторы через этот ключ. Используйте другой действующий ключ, чтобы прочитать итоговый статус запуска, или посмотрите в веб-UI.

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

Заметки по безопасности

Никогда не коммитьте ключи в систему контроля версий. Читайте их из переменных окружения или секрет-менеджера: TRIGGO_API_KEY=trg_…. Добавьте trg_ в allow-list паттернов вашего сканера секретов.
Один ключ — одна интеграция. Если Claude Desktop, CI-пайплайн и Zapier-мост используют общий ключ, вы не сможете отозвать его, не сломав остальных. Разные ключи также дают per-integration сигнал по lastUsedAt.
Сразу отзывайте при подозрении на утечку. Проводите ротацию ниже по течению, потом расследуйте — не ждите.
Предпочитайте узкие права. Ключу для дашборда read-only нужны только actions:read + runs:read. Ключу, который запускает одно действие, нужны actions:run + runs:read.
Ставьте даты истечения для временных интеграций (демо, краткосрочные подрядчики). Просроченные ключи падают на аутентификации автоматически, без ручного отзыва.
Относитесь к открытому ключу как к паролю. Сервер редактирует ключи в логах (оставляя только 8-символьный префикс), но везде в вашем стеке — логи CI, репортеры ошибок, скриншоты — это ваша ответственность.

Связанное

Обзор интеграции с агентами — когда использовать REST, а когда MCP.
Быстрый старт MCP — подключение MCP-клиента.
Лимиты запросов — тарифные лимиты, скользящее окно и обработка 429.

API-ключи

On this page