Доступ по API

Вопрос «дайте API-ключ, я всё сделаю сам» звучит первым при любой интеграции, и честный ответ на него такой: одного ключа ко всей платформе не существует. Есть три разных двери, каждая со своей областью действия и своим сроком жизни. Выбор двери определяется не удобством, а тем, что именно должна делать внешняя система.

1. JWT приложения — для самого интерфейса

Вход в аккаунт возвращает JWT: это то, чем браузер подписывает каждый запрос к /api/…. Токен живёт сутки и отзывается сменой версии токена у пользователя, роль читается из базы на каждый запрос — поэтому повышение и понижение прав действуют мгновенно, а не после переполучения токена.

Технически им можно ходить и из своей программы: заголовок Authorization: Bearer <токен>, базовый путь /api. Но это токен сессии человека, а не выданный интеграции ключ: он протухнет через сутки, у него нет отдельных прав, и всё, что он делает, делается от вашего имени. Для постоянной интеграции это плохая опора.

2. Ключ вебхука — на один воркфлоу

Самая частая задача: «из моей CRM (формы, скрипта, бэкенда) запустить вот этот воркфлоу и получить ответ». Для неё есть отдельный канал — вебхук. Ключ создаётся при первой публикации в этот канал, привязан к одному воркфлоу и не даёт ничего, кроме права его запускать.

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

curl -X POST https://ваш-домен/webhook/<id-воркфлоу> \
  -H "Authorization: Bearer <ключ>" \
  -H "Content-Type: application/json" \
  -d '{"message": "привет", "data": {"order_id": 12345}}'

Про тело запроса: это должен быть JSON-объект, и в нём обязано быть хотя бы одно из двух полей. message — строка, она сохраняется как сообщение пользователя и приходит на вход воркфлоу; data — произвольное значение, оно доступно в контексте триггера как trigger.webhook.payload. Нет ни того, ни другого — ответ 400.

Ответ приходит после того, как запуск завершился: обработчик ставит работу в очередь и ждёт терминального статуса до пяти минут.

{
  "status": "success",
  "result": { "output": "…то, что вернул выход воркфлоу…" },
  "session_id": "…",
  "execution_id": "…"
}

Читать этот ответ надо по трём правилам, каждое из которых экономит день отладки:

• status равен success только для успешного запуска. Запуск, в котором нода упала необработанной ошибкой, но дело всё-таки дошло до выхода (статус partial), отвечает "status": "error" и при этом кладёт вывод в result — по одному лишь наличию result отличить успех от сбоя нельзя. Разбор статусов — в «Статусах».
• При ошибке в поле error приходит машинный код, а не текст исключения: он предназначен для ветвления в вашей системе. Человеческое описание сбоя лежит в «Запусках», у автора воркфлоу.
• session_id из ответа можно подставить в путь — POST /webhook/<id>/<session_id> — и следующий вызов продолжит тот же диалог, с той же историей и памятью. Без него каждый вызов начинает новую сессию. Идентификатор должен быть существующей сессией этого воркфлоу, иначе 404.

Отдельные ответы, которые видно чаще всего: 401 — ключа нет или он не тот; 410 — воркфлоу не опубликован или канал «Вебхук» выключен; 429 — превышен лимит частоты (он считается по IP-адресу вызывающего) либо тарифный лимит глубины очереди этой сессии; "error": "timeout" внутри ответа — запуск не уложился в пять минут, но продолжает идти, и его исход надо смотреть в «Запусках» по execution_id.

3. Ключ Assistant MCP — на весь воркспейс

Третья дверь предназначена не для чужой программы вообще, а для внешнего ИИ-агента (например, Claude Code): он подключается по протоколу MCP и работает инструментами — читает список воркфлоу, забирает граф, правит, валидирует, запускает, читает логи, ходит в базы знаний, коллекции, файлы и историю чатов. Подробно — на странице Assistant MCP.

Ключ выдаётся на воркспейс, начинается с amcp_, показывается один раз (на сервере хранится только его отпечаток) и управляется в Настройки → Assistant MCP: Сгенерировать ключ, Сменить ключ и набор Права — по галочке на возможность. Управлять ключом может только администратор воркспейса; по умолчанию доступ только на чтение, и сервер не просто прячет запрещённые инструменты, а перепроверяет право в момент вызова.

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

Что ключом API не является

Ссылка на публичный чат и токен виджета — это публикация, а не доступ к API. Токен в адресе даёт незалогиненному посетителю право говорить с одним опубликованным воркфлоу и ничего больше: ни чтения чужих данных, ни управления. Он общедоступен по замыслу — так и задумано, что ссылку раздают. Разбор — в «Чате по ссылке» и «Виджете на сайт».

Секреты воркспейса — это доступ наружу, а не внутрь. Ключи, которые вы кладёте в интеграции и секреты, нужны воркфлоу, чтобы ходить в чужие сервисы; к платформе они отношения не имеют.

Если нужен именно «программный доступ ко всему»

Такого токена сегодня нет: нет сервисных аккаунтов, нет OAuth-приложений, нет выдаваемых REST-ключей на воркспейс. Ближайшее средство — Assistant MCP: по покрытию он и есть программный доступ к платформе (воркфлоу, версии, публикация, запуск, отмена, исполнения, логи, базы знаний, коллекции, файлы, история чатов), просто в форме MCP-инструментов, а не REST-эндпоинтов. Правила простые: нужно дёрнуть один воркфлоу из чужой системы — вебхук; нужно управлять платформой программой — Assistant MCP.