Аутентификация и права доступа
API ChurchApps использует аутентификацию на основе JWT. Пользователи входят в систему и получают токен, который содержит их личность, принадлежность к церкви и права доступа. На этой странице описаны процесс аутентификации, модель прав и поддержка OAuth.
Процесс входа
Стандартный вход
POST /membership/users/login
Auth: Public
Принимает один из трёх типов учётных данных:
| Поле | Описание |
|---|---|
email + password | Стандартный вход по email и паролю |
jwt | Повторная аутентификация с существующим JWT |
authGuid | Одноразовая ссылка для входа (используется в письмах с приветствием и сбросом пароля) |
Ответ:
{
"user": {
"id": "abc-123",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@example.com"
},
"churches": [
{
"church": { "id": "church-1", "name": "First Church", "subDomain": "firstchurch" },
"person": { "id": "person-1", "membershipStatus": "Member" },
"groups": [{ "id": "group-1", "name": "Choir", "leader": false }],
"apis": [
{
"keyName": "MembershipApi",
"permissions": [
{ "contentType": "People", "action": "View" },
{ "contentType": "People", "action": "Edit" }
]
}
]
}
],
"token": "<jwt-token>"
}
Поле token — это JWT, который нужно передавать в заголовке Authorization: Bearer <token> в последующих запросах.
Двухфакторный вход
Пользователи могут включить двухфакторный вход через приложение-аутентификатор (TOTP). Для таких пользователей вход по email + password, authGuid или SSO не возвращает токен. Вместо этого сервер отвечает запросом подтверждения:
{ "mfaRequired": true, "mfaToken": "<challenge-token>" }
Токен подтверждения действителен 5 минут. Отправьте его обратно на тот же эндпоинт вместе с кодом:
{ "mfaToken": "<challenge-token>", "mfaCode": "123456" }
В поле mfaCode можно передать текущий 6-значный код из приложения-аутентификатора или один из десяти одноразовых резервных кодов пользователя. Неверный код возвращает Invalid code, а повторные ошибки ограничиваются по каждой учётной записи. Повторный вход по jwt никогда не требует подтверждения, поэтому существующие сеансы продолжают обновляться. Объект user в ответе на вход содержит поле mfaEnabled.
Эндпоинты самообслуживания (только для вошедшего пользователя, по пути /membership/users/mfa):
| Эндпоинт | Описание |
|---|---|
GET /status | { enabled, backupCodesLeft } |
POST /setup | Начинает настройку; возвращает { secret, otpauthUrl } для QR-кода |
POST /enable | Тело { code }; включает вход и возвращает { backupCodes } один раз |
POST /disable | Тело { code } (код из приложения или резервный код); отключает вход |
POST /reset/:userId | Только Server.Admin; отключает вход для другого пользователя |
Секреты хранятся в зашифрованном виде, а резервные коды — в виде хешей. Включение, отключение и сброс записываются в журнал аудита.
Содержимое токена
JWT содержит:
id— ID пользователяchurchId— текущая выбранная церковьpersonId— запись человека для выбранной церкви- Массивы прав для каждого API
Выбор церкви
Пользователь может состоять в нескольких церквях. Ответ на вход содержит все церкви с их правами. Чтобы переключиться на другую церковь, клиент формирует новый JWT, привязанный к другой церкви, на основе данных из ответа на вход.
Регистрация пользователей
Регистрация нового пользователя
POST /membership/users/register
Auth: Public
{
"email": "jane@example.com",
"firstName": "Jane",
"lastName": "Doe",
"appName": "B1 Admin",
"appUrl": "https://app.b1.church"
}
Создаёт пользователя с временным паролем и отправляет приветственное письмо со ссылкой для входа. Первому пользователю, зарегистрированному на новом экземпляре, автоматически предоставляется доступ администратора сервера.
Принимаются два необязательных поля-ловушки для ботов: website (скрытое поле-приманка, которое реальные пользователи оставляют пустым) и fillMs (сколько миллисекунд форма была открыта). Если заполнено website или fillMs меньше 2000, учётная запись не создаётся, но эндпоинт всё равно возвращает обычный ответ 200, чтобы боты не могли понять, что их отклонили. Клиенты, которые не передают оба поля, регистрируются обычным образом.
Регистрация новой церкви
POST /membership/churches/add
Auth: JWT
После регистрации пользователя вызовите этот эндпоинт, чтобы создать церковь и связать с ней пользователя.
Управление паролями
| Метод | Путь | Auth | Описание |
|---|---|---|---|
| POST | /membership/users/forgot | Public | Отправить письмо со сбросом пароля. Тело: { "userEmail": "...", "appName": "...", "appUrl": "..." } |
| POST | /membership/users/setPasswordGuid | Public | Задать новый пароль по auth GUID из письма для сброса. Тело: { "authGuid": "...", "newPassword": "..." } |
| POST | /membership/users/updatePassword | JWT | Сменить пароль текущего пользователя. Тело: { "newPassword": "..." } |
Модель прав доступа
Права организованы по модулям и назначаются пользователям через роли. У каждого права есть content type (тип содержимого) и action (действие).
Справочник прав
| Раздел в интерфейсе | Content Type | Action | Описание |
|---|---|---|---|
| Attendance | Attendance | Checkin | Регистрация участников на службах |
| Attendance | Edit | Редактирование записей посещаемости | |
| Services | Edit | Управление службами и временами служений | |
| Attendance | View | Просмотр записей посещаемости | |
| Attendance | View Summary | Просмотр сводок и отчётов по посещаемости | |
| Donations | Donations | Edit | Создание и редактирование записей о пожертвованиях |
| Settings | Edit | Редактирование настроек пожертвований и платежей | |
| Donations | View Summary | Просмотр сводных отчётов по пожертвованиям | |
| Donations | View | Просмотр отдельных записей о пожертвованиях | |
| People and Groups | Forms | Admin | Полное администрирование форм |
| Forms | Edit | Редактирование определений форм | |
| Plans | Edit | Редактирование планов служения | |
| Group Members | Edit | Добавление и удаление участников групп | |
| Groups | Edit | Создание и редактирование групп | |
| Households | Edit | Редактирование назначений домохозяйств | |
| People | Edit | Редактирование любой записи о человеке | |
| People | Edit Self | Редактирование только собственной записи | |
| Roles | Edit | Управление ролями и назначениями пользователей | |
| Group Members | View | Просмотр списков участников групп | |
| People | View Members | Просмотр только участников (не гостей) | |
| People | View | Просмотр всех людей | |
| Roles | View | Просмотр ролей и назначений | |
| Settings | Edit | Редактирование настроек церкви | |
| Content | Content | Edit | Редактирование страниц, разделов, элементов |
| Settings | Edit | Редактирование настроек контента | |
| StreamingServices | Edit | Управление конфигурацией служб трансляций | |
| Chat | Host | Ведение и модерация чат-сессий | |
| Messaging | Texting | Send | Отправка SMS-сообщений |
Как проверяются права
В контроллерах права проверяются методом au.checkAccess():
// Требуется конкретное право
if (!au.checkAccess(Permissions.people.edit)) return this.json({}, 401);
// Или внутри actionWrapper — CRUD-система проверяет автоматически
crudSettings: {
permissions: {
view: Permissions.people.view,
edit: Permissions.people.edit
}
}
Server Admin
Право Server.Admin даёт полный доступ ко всем церквям. Оно назначается первому зарегистрированному пользователю и может быть передано другим через роль администратора сервера.
OAuth 2.0
API поддерживает OAuth 2.0 для сторонних интеграций. Доступны два типа грантов.
Authorization Code Flow
-
Авторизация:
POST /membership/oauth/authorize(требуется JWT)- Тело:
{ "client_id": "...", "redirect_uri": "...", "response_type": "code", "scope": "...", "state": "...", "code_challenge": "...", "code_challenge_method": "S256" } code_challenge/code_challenge_method(PKCE, толькоS256) обязательны для публичных клиентов без секрета- Возвращает:
{ "code": "...", "state": "..." }
- Тело:
-
Обмен кода на токен:
POST /membership/oauth/token(Public)- Тело:
{ "grant_type": "authorization_code", "code": "...", "client_id": "...", "client_secret": "...", "redirect_uri": "...", "code_verifier": "..." } - Передавайте
code_verifier, если на шаге авторизации использовалсяcode_challenge; публичные клиенты не передаютclient_secret. Принимаются тела в формате JSON или form-encoded - Возвращает:
{ "access_token": "...", "token_type": "Bearer", "expires_in": 43200, "refresh_token": "...", "scope": "..." }
- Тело:
-
Обновление токена:
POST /membership/oauth/token(Public)- Тело:
{ "grant_type": "refresh_token", "refresh_token": "...", "client_id": "...", "client_secret": "..." }
- Тело:
Срок действия access-токенов — 12 часов.
Device Code Flow (RFC 8628)
Для устройств без браузера (приложения для телевизоров, киоски):
-
Запрос кода устройства:
POST /membership/oauth/device/authorize(Public)- Тело:
{ "client_id": "...", "scope": "..." } - Возвращает:
{ "device_code": "...", "user_code": "ABCD-1234", "verification_uri": "https://app.b1.church/device", "expires_in": 900, "interval": 5 }
- Тело:
-
Пользователь вводит код на странице verification URI и подтверждает или отклоняет запрос
-
Опрос для получения токена:
POST /membership/oauth/token(Public)- Тело:
{ "grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": "...", "client_id": "..." } - Возвращает
authorization_pending, пока запрос не подтверждён, затем возвращает access-токен
- Тело:
Управление OAuth-клиентами
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | /membership/oauth/clients | JWT | Server.Admin | Список всех OAuth-клиентов |
| GET | /membership/oauth/clients/:id | JWT | Server.Admin | Получить клиента по ID |
| GET | /membership/oauth/clients/clientId/:clientId | JWT | — | Получить клиента по client ID (секрет скрыт) |
| POST | /membership/oauth/clients | JWT | Server.Admin | Создать или обновить клиента |
| DELETE | /membership/oauth/clients/:id | JWT | Server.Admin | Удалить клиента |
| POST | /membership/oauth/register | Public | — | Динамическая регистрация клиента (RFC 7591) для публичных клиентов, например MCP-коннекторов. См. Connected Apps |
Эндпоинты подтверждения устройств
| Метод | Путь | Auth | Описание |
|---|---|---|---|
| GET | /membership/oauth/device/pending/:userCode | JWT | Получить сведения об ожидающем коде устройства для интерфейса подтверждения |
| POST | /membership/oauth/device/approve | JWT | Подтвердить авторизацию устройства. Тело: { "user_code": "...", "church_id": "..." } |
| POST | /membership/oauth/device/deny | JWT | Отклонить авторизацию устройства. Тело: { "user_code": "..." } |
Публичные и аутентифицированные эндпоинты
API использует две обёртки функций, которые определяют требования к аутентификации:
actionWrapper— требует действительный JWT. Объект аутентифицированного пользователя (au) доступен сchurchId,userIdи проверками прав.actionWrapperAnon— аутентификация не требуется. Используется для входа, регистрации, публичных запросов контента и приёмников вебхуков.
В таблицах эндпоинтов этой документации они обозначены в колонке Auth как JWT и Public соответственно.
Связанные страницы
- Структура модулей — как организованы контроллеры, репозитории и модели
- Локальная установка — запуск API локально для разработки