Аутентификация и разрешения

API ChurchApps использует аутентификацию на основе JWT. Пользователи входят в систему для получения токена, который кодирует их идентичность, членство в церкви и разрешения. На этой странице рассматриваются процесс аутентификации, модель разрешений и поддержка OAuth.

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

Стандартный вход

POST /membership/users/login

Аутентификация: Публичный

Принимает один из трёх типов учётных данных:

Поле	Описание
`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> в последующих запросах.

Содержимое токена

JWT кодирует:

id — ID пользователя
churchId — текущая выбранная церковь
personId — запись о человеке для выбранной церкви
Массивы разрешений для каждого API

Выбор церкви

Пользователи могут принадлежать нескольким церквям. Ответ на вход включает все церкви с их разрешениями. Для переключения между церквями клиент генерирует новый JWT, ограниченный другой церковью из данных ответа на вход.

Регистрация пользователя

Регистрация нового пользователя

POST /membership/users/register

Аутентификация: Публичный

{
  "email": "jane@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "appName": "B1 Admin",
  "appUrl": "https://app.b1.church"
}

Создаёт пользователя с временным паролем и отправляет приветственное письмо со ссылкой аутентификации. Первый зарегистрированный пользователь на новом экземпляре автоматически получает права администратора сервера.

Регистрация новой церкви

POST /membership/churches/add

Аутентификация: JWT

После регистрации пользователя вызовите этот эндпоинт для создания церкви и привязки к ней пользователя.

Управление паролями

Метод	Путь	Аутентификация	Описание
POST	`/membership/users/forgot`	Публичный	Отправить письмо для сброса пароля. Тело: `{ "userEmail": "...", "appName": "...", "appUrl": "..." }`
POST	`/membership/users/setPasswordGuid`	Публичный	Установить новый пароль по GUID аутентификации из письма сброса. Тело: `{ "authGuid": "...", "newPassword": "..." }`
POST	`/membership/users/updatePassword`	JWT	Изменить пароль текущего пользователя. Тело: `{ "newPassword": "..." }`

Модель разрешений

Разрешения организованы по модулям и назначаются пользователям через роли. Каждое разрешение имеет тип контента и действие.

Справочник разрешений

Раздел	Тип контента	Действие	Описание
Посещаемость	Attendance	Checkin	Регистрация участников на служениях
	Attendance	Edit	Редактирование записей посещаемости
	Services	Edit	Управление служениями и временами служений
	Attendance	View	Просмотр записей посещаемости
	Attendance	View Summary	Просмотр сводок и отчётов по посещаемости
Пожертвования	Donations	Edit	Создание и редактирование записей о пожертвованиях
	Settings	Edit	Редактирование настроек пожертвований/платежей
	Donations	View Summary	Просмотр сводных отчётов по пожертвованиям
	Donations	View	Просмотр отдельных записей о пожертвованиях
Люди и группы	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	Edit	Редактирование страниц, разделов, элементов
	Settings	Edit	Редактирование настроек контента
	StreamingServices	Edit	Управление конфигурацией потоковых служб
	Chat	Host	Ведение/модерация чат-сессий
Сообщения	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 предоставляет полный доступ ко всем церквям. Оно назначается первому зарегистрированному пользователю и может быть предоставлено другим через роль администратора сервера.

OAuth 2.0

API поддерживает OAuth 2.0 для сторонних интеграций. Доступны два типа предоставления.

Поток кода авторизации

Авторизация: POST /membership/oauth/authorize (требуется JWT)
- Тело: { "client_id": "...", "redirect_uri": "...", "response_type": "code", "scope": "...", "state": "..." }
- Возвращает: { "code": "...", "state": "..." }
Обмен кода на токен: POST /membership/oauth/token (Публичный)
- Тело: { "grant_type": "authorization_code", "code": "...", "client_id": "...", "client_secret": "...", "redirect_uri": "..." }
- Возвращает: { "access_token": "...", "token_type": "Bearer", "expires_in": 43200, "refresh_token": "...", "scope": "..." }
Обновление токена: POST /membership/oauth/token (Публичный)
- Тело: { "grant_type": "refresh_token", "refresh_token": "...", "client_id": "...", "client_secret": "..." }

Токены доступа истекают через 12 часов.

Поток кода устройства (RFC 8628)

Для устройств без браузера (ТВ-приложения, киоски):

Запрос кода устройства: POST /membership/oauth/device/authorize (Публичный)
- Тело: { "client_id": "...", "scope": "..." }
- Возвращает: { "device_code": "...", "user_code": "ABCD-1234", "verification_uri": "https://app.b1.church/device", "expires_in": 900, "interval": 5 }
Пользователь вводит код по URI верификации и одобряет или отклоняет
Опрос токена: POST /membership/oauth/token (Публичный)
- Тело: { "grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": "...", "client_id": "..." }
- Возвращает authorization_pending до одобрения, затем возвращает токен доступа

Управление OAuth-клиентами

Метод	Путь	Аутентификация	Разрешение	Описание
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	Удалить клиента

Эндпоинты одобрения устройств

Метод	Путь	Аутентификация	Описание
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 — Аутентификация не требуется. Используется для входа, регистрации, публичных поисков контента и приёмников вебхуков.

В таблицах эндпоинтов этой документации они обозначены как JWT и Public соответственно в столбце «Аутентификация».

Связанные страницы

Структура модулей — Организация контроллеров, репозиториев и моделей
Локальная настройка — Запуск API локально для разработки

Процесс входа​

Стандартный вход​

Содержимое токена​

Выбор церкви​

Регистрация пользователя​

Регистрация нового пользователя​

Регистрация новой церкви​

Управление паролями​

Модель разрешений​

Справочник разрешений​

Как проверяются разрешения​

Администратор сервера​

OAuth 2.0​

Поток кода авторизации​

Поток кода устройства (RFC 8628)​

Управление OAuth-клиентами​

Эндпоинты одобрения устройств​

Публичные и аутентифицированные эндпоинты​

Связанные страницы​