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