Для AI-агентов: markdown этой страницы — /docs-content/applications/app-login.md индекс документации — /llms.txt

Вход пользователей приложения

Готовый вход для клиентов и других людей без доступа к вашему Битрикс24: приложение на Node.js подключает SDK входа платформы, а платформа раздаёт этот SDK, заводит секрет входа и передаёт приложению служебные переменные.

Страница описывает, как вход включает AI-агент по вашей просьбе, какие методы API он вызывает и что значат статусы и отказы. Устройство секретов и переменных входа — в разделе «Приложения со встроенным входом» страницы Секреты приложения. Как подключить SDK в коде приложения — Подключение SDK входа, как работать с пользователями, ролями и данными входа — Обслуживание входа.

Авторизация: X-Api-Key со скоупом vibe:infra. Методы вызывает владелец сервера приложения своим ключом в этом Битрикс24. Какие серверы доступны ключу:

  • Личный ключ без привязки к приложению — любой сервер владельца, все три метода.
  • Ключ, привязанный к приложению, — только сервер этого приложения. На сервере другого приложения все три метода отвечают 404 SERVER_NOT_FOUND. Привязаны личный API-ключ приложения из его карточки и ключ авторизации (vibe_app_) приложения, у которого есть карточка.
  • Ключ авторизации без привязки к приложению читает setup и status любого сервера владельца, а enable ему отвечает 404 SERVER_NOT_FOUND: включать вход ключ авторизации может только своему приложению.

Включить вход может только тот, кому принадлежат и сервер, и карточка приложения. Пока функция не открыта владельцу ключа, методы отвечают 404 ROUTE_NOT_FOUND.

Для кого вход

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

  • Коллеги из вашего Битрикс24. Вход не нужен: приложение закрыто шлюзом платформы, и коллеги открывают его со своей учётной записью Битрикс24.
  • Клиенты и люди со стороны. Нужен вход через SDK: человек регистрируется в самом приложении.
  • И те, и другие. Если приложению доступен вход через Битрикс24, всё идёт через SDK: сотрудники входят кнопкой «Битрикс24» и получают роль в админке. Если недоступен — нужны два приложения: одно для коллег за шлюзом, другое для клиентов со входом.

Текст вопроса и его ветки агент получает в data.capabilities.appUserSignIn.guidance.text ответа GET /v1/me. Там же принципы: не писать свой вход, не хранить пароли, подключать SDK.

Что нужно приложению:

  • Node.js 24.15 или новее на Express или node:http, деплой с runtime: node24.
  • Свой сервер приложения — не хост галактики и не сервер AI-агента.
  • Карточка приложения у этого сервера.
  • На отдельной машине — запуск службой платформы: деплой с systemd: true и командой запуска самого приложения.

Фраза агенту

Скажите агенту: «Сделай в приложении вход для клиентов». Дальше агент работает сам:

  1. Читает GET /v1/me: слот capabilities.appUserSignIn.setup говорит, доступна ли настройка входа, capabilities.appUserSignIn.enable — может ли этот ключ включить вход сам.
  2. Читает настройку входа GET /v1/app-user-signin/servers/{serverId}/setup. Шаги по порядку лежат в enableFlow.steps.
  3. Включает вход инструментом MCP enable_app_login или методом POST …/enable. Если инструмента нет или слот enable закрыт, агент просит вас нажать «Включить вход» в карточке приложения.
  4. Ставит SDK по sdk.installCommand, сверяет sdk.integrity с package-lock.json, подключает auth.express() до парсеров тела и деплоит.
  5. Создаёт админа приложения и показывает вам ссылку установки.
  6. Проверяет результат статусом входа.

Инструменты MCP входа — get_app_login_setup, get_app_login_status и enable_app_login, полный сценарий — add-user-login. Первые два появляются, когда открыт слот setup, enable_app_login — когда открыт слот enable. MCP-сервер читает слоты при запуске: после их смены перезапустите его.

Что делает включение

enable_app_login и POST …/enable делают то же, что кнопка «Включить вход» в карточке:

  • Заводят системный секрет VIBE_AUTH_SECRET и передают его приложению вместе со служебными переменными входа. AUTH_SECRET автору заводить не нужно, секрет в ответ не попадает.
  • Работают и до первого деплоя, и после неудачного. Деплой SDK 0.4 без включённого входа падает с ошибкой VIBE_AUTH_SECRET is missing: включите вход и повторите деплой.
  • Выбирают режим: new — в приложении ещё не было входа, pilot — приложение работало на входе 0.3 и переводится со своими пользователями.
  • Повторный вызов отвечает already_enabled и ничего не меняет.

Выключить вход нельзя: секреты и переменные входа снимаются только вместе с приложением и его сервером.

Слот capabilities.appUserSignIn.enable закрыт с причиной в reason. Причины проверяются в этом порядке:

  • FEATURE_DISABLED — функция не открыта владельцу ключа. Включить вход нельзя ни методом, ни кнопкой.
  • INFRA_SCOPE_REQUIRED — у ключа нет скоупа vibe:infra. Вход включают кнопкой в карточке или ключом с этим скоупом.
  • APP_LOGIN_SDK_NOT_SERVED — платформа в целом ещё раздаёт SDK входа 0.3. Кнопка включит вход, только если приложению SDK 0.4 открыли раньше, иначе ответит 409 APP_LOGIN_SDK_NOT_SERVED. Подробнее — в разделе «Пока SDK 0.4 открыт не всем».
  • WRITE_BLOCKED_READONLY_KEY — ключ только для чтения. Вход включают кнопкой в карточке или ключом с правом записи.

Админ по ссылке установки

Первого администратора создаёт агент: выполняет на сервере команду npx --no-install vibecode-auth create-admin синхронным exec. Точную команду для этого сервера даёт последний шаг enableFlow.steps. Шаг есть у приложения на SDK 0.4.1 или новее.

Команда печатает одну строку — ссылку вида https://…/_auth/setup-admin#vauth:t=…. Откройте её в течение 15 минут и войдите: так вы станете владельцем приложения в его админке. Ссылка одноразовая. Агент её не открывает и не сохраняет: открытая им ссылка сделала бы владельцем не вас.

  • Ссылка истекла или потерялась — агент запускает команду ещё раз, каждый запуск выпускает новую. Каждая открытая ссылка добавляет владельца.
  • Приложение передали вам или прежние владельцы мешают — команда с флагом --reset. Такая ссылка оставит владельцем одного того, кто её откроет, у остальных снимет права и завершит сессии. Это не отменить.
  • Страница ссылки ответила «Нет способа входа» — ссылке нужен хотя бы один способ входа до мастера. Пока приложению недоступен вход через Битрикс24, блок env настройки называет два идентификатора клиента, AUTH_VK_CLIENT_ID и AUTH_YANDEX_CLIENT_ID. Автор задаёт в env деплоя хотя бы один из них и не убирает его, пока вход через Битрикс24 недоступен. Шаги регистрации — в providers. Исключение — причина SERVER_NOT_PUBLIC в поле bitrix24: блок env пуст и идентификатор клиента не нужен. Откройте приложение всем, политика PUBLIC на вкладке «Доступ», и ссылка предложит вход через Битрикс24.

Мастер и статусы

Вход клиентов закрыт, пока владелец не откроет ссылку установки и не пройдёт мастер в админке приложения. Способы входа и политику обработки персональных данных задают в мастере. Переменная с тем же именем в env деплоя запирает поле мастера, поэтому политику в env не передают.

Статус входа агент читает GET …/status, вы видите его в карточке приложения:

state Что значит
stateworking Что значитВход работает, в providers — способы, через которые можно войти.
statesetup_pending Что значитSDK 0.4.1 или новее отвечает, но мастер не пройден: клиенты пока не входят. Откройте ссылку установки и пройдите мастер.
statenot_configured Что значитSDK старше 0.4.1 отвечает, но вход не настроен: в env деплоя нет способа входа или политики.
statenot_installed Что значитПриложение отвечает, а SDK входа в нём нет.
stateoutdated Что значитSDK стоит, но его версия не умеет отвечать на проверку. Обновите SDK до версии из настройки.
stateunreachable Что значитПриложение не ответило на проверку.
statesleeping Что значитСервер спит. Платформа его не будит и отдаёт последний известный результат.
statenot_public Что значитПриложение открыто не всем. Клиенты войдут, когда вы откроете его на вкладке «Доступ». Проверка не идёт, приходит последний известный результат.
stateunsupported_runtime Что значитПриложение не на Node.js 24: вход недоступен.

Карточка приложения в блоке «Вход пользователей» показывает версию SDK входа с пометкой «Устарела» или «Уязвимая версия», строку «Мастер не пройден» и есть ли у приложения администратор.

Пока SDK 0.4 открыт не всем

Платформа открывает SDK входа 0.4 не всем приложениям сразу, остальным пока раздаёт SDK 0.3. Какой SDK раздаётся приложению, показывает ответ настройки входа его сервера:

  • sdk.version начинается с 0.3, а полей enableFlow и bitrix24 в ответе нет — приложению раздаётся SDK 0.3.
  • sdk.version — 0.4 или новее, в ответе есть enableFlow — приложению раздаётся SDK 0.4, вход включают, как описано выше.

Причина APP_LOGIN_SDK_NOT_SERVED в слоте capabilities.appUserSignIn.enable говорит о платформе в целом: отдельному приложению SDK 0.4 могут открыть раньше. Решайте по ответу настройки своего сервера.

На SDK 0.3 вход не включают: кнопка и POST …/enable отвечают 409 APP_LOGIN_SDK_NOT_SERVED. Приложение настраивают по ответу настройки:

  • SDK ставят по sdk.installCommand и sdk.driverInstall, подсказки deployHints передают в деплой как есть.
  • Секрет AUTH_SECRET автор создаёт сам и передаёт секретом приложения или через env деплоя: платформа его не заводит.
  • В env деплоя передают переменные из блока env настройки: адрес APP_URL, идентификатор клиента хотя бы одного способа входа, политику AUTH_PRIVACY_URL и AUTH_PRIVACY_VERSION.
  • Ссылки установки и мастера на SDK 0.3 нет. Админом становится тот, чью строку AUTH_ADMINS=… после первого входа скопировали со страницы /_auth/account в env деплоя.

Когда платформа откроет приложению SDK 0.4, включение переведёт работающий вход 0.3 в режиме pilot, как описано в разделе ниже.

Переход с входа 0.3

Приложение, у которого уже работал вход 0.3, включение переводит в режиме pilot. Платформа находит прежний AUTH_SECRET в окружении приложения и сохраняет его системным секретом VIBE_AUTH_SECRET_PREVIOUS, поэтому сессии пользователей переживают переход на SDK 0.4. Способы входа и политика, которые уже лежат в env деплоя, остаются там до прохождения мастера: без них вход клиентов закроется.

Где платформа ищет секрет, когда перестаёт доставлять прежний и как действует откат на 0.3 — в разделе «Приложения со встроенным входом» страницы Секреты приложения.

GET /v1/app-user-signin/servers/:serverId/setup

GET /v1/app-user-signin/servers/:serverId/setup

Возвращает готовую настройку входа для приложения этого сервера: адреса возврата, хранилище, команды установки SDK, переменные env, подсказки деплоя, шаги регистрации способов входа и порядок шагов enableFlow. Только читает.

Поля, которые нужны агенту для включения:

Поле Описание
Полеsdk ОписаниеВерсия SDK version, хеш пакета integrity, команда установки installCommand и проверка драйвера хранилища driverInstall.
Полеenv ОписаниеПеременные, которые задаёт автор. С SDK 0.4.1, когда приложению доступен вход через Битрикс24, список пуст. Пока недоступен — два необязательных идентификатора клиента AUTH_VK_CLIENT_ID и AUTH_YANDEX_CLIENT_ID, из которых автор задаёт хотя бы один. При причине SERVER_NOT_PUBLIC список пуст: вход заработает, когда автор откроет приложение всем. На SDK 0.4.0 — способы входа и политика AUTH_PRIVACY_URL, AUTH_PRIVACY_VERSION.
Полеproviders ОписаниеСпособы входа, key, title и шаги регистрации steps.
Полеbitrix24 ОписаниеТолько при SDK 0.4 и новее. Заработает ли у приложения этого сервера вход через Битрикс24: платформа доставляет его приложению и разрешает на этом сервере. available — true или false. reason — null, когда вход доступен, иначе код причины: PLATFORM_UNSUPPORTED — эта установка платформы вход через Битрикс24 не предлагает, NO_APPLICATION — у сервера нет карточки приложения, FEATURE_DISABLED — возможность не открыта владельцу приложения или владельцу сервера, SERVER_NOT_BLACKHOLE — сервер работает в открытом режиме OPEN, а вход через Битрикс24 работает только в защищённом режиме Black Hole. Автор возвращает сервер в Black Hole переключателем режима в кабинете или методом Переключить режим с mode: "BLACKHOLE". SERVER_NOT_PUBLIC — вход через Битрикс24 у владельца включён, но приложение открыто не всем. Автор ставит политику PUBLIC на вкладке «Доступ», и вход заработает. С SDK 0.4.1 идентификаторы клиента VK и Яндекса в этом случае не нужны: env пуст, а шаги enableFlow ведут к открытию доступа. SERVER_OWNER_BLOCKED — учётная запись владельца сервера заблокирована или удалена.
ПолеdocsUrl ОписаниеСсылка на эту страницу.
ПолеenableFlow.enabled ОписаниеВключён ли вход у приложения.
ПолеenableFlow.steps ОписаниеШаги по порядку. С SDK 0.4.1 — пять шагов: включение, установка SDK, деплой, доступ, создание админа. На SDK 0.4.0 — четыре, без создания админа. Режим восстановления — два шага: пояснение и создание админа, без установки и деплоя. Он приходит, когда вход включён и последний деплой записал SDK 0.4.1 или новее.

Список providers может назвать Битрикс24 и при bitrix24.available: false. Доступен ли приложению этот вход, решает только поле bitrix24: пока там false, ссылке установки нужен идентификатор клиента из env. Исключение — причина SERVER_NOT_PUBLIC: вместо идентификатора клиента автор открывает приложение всем.

Слот capabilities.appUserSignIn.setup в GET /v1/me несёт путь этого метода endpoint, путь статуса statusEndpoint и ссылку на эту страницу docs. Слот capabilities.appUserSignIn.bitrix24 там же отвечает на тот же вопрос про вход через Битрикс24 для приложений владельца ключа, без сервера: причина FEATURE_DISABLED или PLATFORM_UNSUPPORTED.