Поверхня інтеграцій і розширень
Усе, що сторонній сервіс може підключити, працює через один API і одну модель авторизації. Ця сторінка є картою: вона називає кожну поверхню інтеграції, показує, як вони пов'язані, і посилається на детальний довідник для кожної з них. Якщо ви створюєте щось для B1, почніть звідси, щоб обрати потрібний вхід, а потім перейдіть за посиланням на сторінку, де це описано докладно.
Поверхні з першого погляду
Є шість способів увійти в систему або вийти з неї, і всі вони використовують один і той самий рівень автентифікації:
- REST API — уся функціональність продукту, доступна з bearer-токеном із будь-якої мови програмування.
- API-ключі — найпростіший обліковий запис: токен
cak_…, прив'язаний до однієї особи в одній церкві. - OAuth 2.0 і підключені застосунки — погодження на рівні церкви для багатокористувацьких застосунків; видає той самий JWT, який отримує користувач.
- Вебхуки — підписані вихідні події з гарантованою доставкою.
- Сервер MCP — обгортка для ШІ над REST API за адресою
/mcp. - Провайдери контенту — вхідний шлях для зовнішніх медіабібліотек у FreePlay і застосунки B1.
Усе, крім провайдерів контенту, обслуговується єдиним монолітним API (репозиторій Api), модулі якого підключено за стабільними базовими шляхами: /membership, /giving, /attendance, /content, /messaging, /doing, /reporting і /mcp.
Як це поєднується
┌─────────────────────┐ ┌───────────────────────────────────────┐
│ Third-party app │ Bearer cak_… / JWT │ B1 API (Api) │
│ · server / SaaS │ ───────────────────────▶ │ ┌─────────────────────────────────┐ │
│ · Zapier / Make │ │ │ CustomAuthProvider.getUser() │ │
│ · Google Sheets │ │ │ cak_ key ─┐ │ │
│ · CLI / scripts │ │ │ OAuth JWT ┴▶ Principal │ │
│ · AI client (MCP) │ ─── POST /mcp ──────────▶ │ │ scopes filter → permissions[] │ │
└─────────────────────┘ │ └────────────────┬────────────────┘ │
▲ │ ▼ │
│ │ API modules: /membership /giving │
│ signed JSON POST │ /attendance /content /messaging … │
│ (person / donation / group / …) │ │ │
└──────────── webhooks ◀─────────────────┼─ shared/webhooks/WebhookDispatcher │
(durable, HMAC-SHA256 signed) └───────────────────────────────────────┘
External content sources (Planning Center, Dropbox, Life.Church, CBN, …)
│ OAuth PKCE / device flow / none ── B1 is the OAuth *client* here ──▶
▼
Packages/content-providers ──▶ FreePlay / B1 apps (inbound content path)
Три стрілки передають головне: сторонній сервіс звертається до системи з bearer-токеном (ключ API або JWT OAuth, зокрема через /mcp); API надсилає виклики назад через підписані вебхуки; а провайдери контенту є єдиним вхідним шляхом контенту, де сам B1 виступає клієнтом OAuth і отримує медіа із зовнішнього джерела.
Спільна модель автентифікації
Кожен обліковий запис, тобто JWT для входу користувача, токен доступу OAuth або ключ API, розв'язується до того самого Principal і перевіряється однаково. Окремого шляху «інтеграційної автентифікації» немає: обмежений обліковий запис просто не відрізняється від користувача з меншими привілеями.
Структура JWT
Токени доступу B1 є JWT HS256, які створюються в Api/src/modules/membership/auth/AuthenticatedUser.ts. Набір claim-ів:
| Claim | Значення |
|---|---|
id, email, firstName, lastName | Особа, яка стоїть за токеном |
churchId | Єдина церква, у межах якої діє токен — основа для розмежування всіх даних |
personId | Запис особи в межах цієї церкви |
permissions | Плоский масив рядків дозволів RBAC ([apiName_]contentType_contentId_action) |
groupIds, leaderGroupIds | Членство в групах і керівництво ними для перевірок на рівні групи |
membershipStatus | Гість чи член церкви, для обмеження самообслуговування |
Токен доступу OAuth має ту саму структуру, що й JWT для входу. Єдина відмінність полягає в тому, що його масив permissions був відфільтрований за наданими областями доступу перед підписанням (getCombinedApiJwt(...)).
Прив'язка до церкви
churchId є claim-ом токена, а не параметром запиту, тож обліковий запис ніколи не може отримати доступ до даних інших церков. Кожен запит до репозиторію фільтрується за churchId викликача; ключ API або токен OAuth прив'язується рівно до однієї церкви в момент створення.
Рольові дозволи на межі
Контролери обмежують дії викликом au.checkAccess(contentType, action) щодо масиву permissions токена. Області доступу є фільтром, а не наданням прав (Api/src/shared/auth/Scopes.ts): SCOPE_CATALOG зіставляє кожну область (наприклад, people:read, donations:write) з парами RBAC, які вона дозволяє, а filterPermissionsByScopes() перетинає це з поточними дозволами особи під час кожного розв'язання. Наслідки:
- Відкликання дозволу в B1Admin припиняє доступ облікового запису вже під час наступного запиту: токени ніколи не розходяться з роллю.
- Область може лише вилучати дозволи, тож обмежений обліковий запис ніколи не отримає права адміністрування сервера чи домену (ці дозволи навмисно не зіставлені з жодною областю).
- Ключі API мають префікс
cak_;CustomAuthProvider.getUser()розпізнає його, хешує секрет і під час кожного виклику повторно перевіряє живий RBAC власника.
Повний каталог дивіться в API-ключі → Області доступу.
Довідник поверхонь
REST API
Повна функціональність продукту. Будь-яка автентифікована кінцева точка приймає або JWT, або ключ cak_… у заголовку Authorization: Bearer. Окремої таблиці маршрутів лише для ключів або лише для OAuth немає. Модулі та їхні базові шляхи розміщені в Api/src/modules/*.
API-ключі
Персональний токен доступу cak_<prefix>.<secret>, який створюється в B1Admin → Settings → Developer → API Keys. Зберігається лише хеш SHA-256; сирий ключ показується один раз. Керується за адресою /membership/apiKeys (Api/src/modules/membership/controllers/ApiKeyController.ts). Найкраще підходить для власних скриптів однієї церкви та для з'єднувачів, як-от Zapier, Make і Google Sheets. → API-ключі
OAuth 2.0 і підключені застосунки
Для багатокористувацьких застосунків, яким потрібне погодження кожної церкви. Реалізовано в Api/src/modules/membership/controllers/OAuthController.ts за шляхом /membership/oauth. Сервер підтримує три типи надання доступу:
- Код авторизації (Authorization Code) —
POST /oauth/authorize(з автентифікацією) повертає короткочасний код;POST /oauth/tokenзgrant_type=authorization_codeобмінює його на токен доступу JWT (≈ 7 днів) і токен оновлення (≈ 90 днів). Публічні клієнти без секрету мусять використовувати PKCE (лишеS256):code_challengeпри авторизації та відповіднийcode_verifierпри обміні токена. - Код пристрою (Device Code, RFC 8628) —
POST /oauth/device/authorizeвидаєuser_code; користувач схвалює його в B1Admin (/oauth/device/approve); пристрій опитує/oauth/tokenз типом надання device-code. Призначено для телевізорів, кіосків і CLI без браузера. - Токен оновлення (Refresh Token) —
grant_type=refresh_tokenстворює новий токен доступу; публічні клієнти без секрету можуть його не передавати.
Публічні клієнти також можуть самостійно зареєструватися через POST /oauth/register (динамічна реєстрація клієнтів за RFC 7591). Вони отримують client_id без секрету, а їхні URI перенаправлення мають бути https або loopback.
Підключений застосунок — це представлення отриманого токена для адміністратора церкви. Його видно та можна відкликати за адресою /membership/oauth/connections. Контролер також містить міст relay-сесій OAuth (/oauth/relay/*), який дає змогу пристрою без браузера завершити вхід через зовнішнього провайдера. → Підключені застосунки та OAuth
Вебхуки
Єдина вихідна поверхня. Церква підписує публічну HTTPS-кінцеву точку на події. Коли відбувається відповідна зміна, WebhookDispatcher.emit(churchId, event, payload) доповнює payload-и лише з ідентифікаторами відображуваними назвами (personName, groupName, formName; пошук виконується лише тоді, коли є відповідна підписка), реєструє доставку, а фоновий обробник надсилає підписаний JSON-конверт POST-запитом із повторними спробами, затримкою та повторною доставкою. Рушій розміщено в Api/src/shared/webhooks/, а CRUD для кожної церкви — за шляхом /membership/webhooks (WebhookController.ts). Поле connectorType змінює тіло запиту для Slack і Discord. З'єднувач mailchimp іде далі й сам керує всім HTTP-обміном (метод, URL і автентифікація для кожної події відповідно до API Mailchimp; облікові дані зберігаються в зашифрованому вигляді в webhooks.connectorConfig). → Вебхуки
Сервер MCP
Обгортка для ШІ за адресою /mcp (Api/src/modules/mcp/). Три загальні інструменти, list_endpoints, describe_endpoint і api_call, динамічно відкривають весь REST-інтерфейс для будь-якого клієнта MCP. Автентифікація така сама, як і для всього іншого: той самий bearer-токен. Для клієнтів, що входять через OAuth (користувацькі коннектори claude.ai), відповідь 401 від /mcp містить заголовок WWW-Authenticate, який вказує на /.well-known/oauth-protected-resource. Адреса /.well-known/oauth-authorization-server оголошує кінцеві точки /membership/oauth, динамічну реєстрацію, PKCE і сторінку погодження B1Admin /oauth (WellKnownController.ts, OAuthMetadata.ts). api_call повторно входить у стек Express всередині процесу, тож усі правила дозволів і розмежування за церквами продовжують діяти. → Сервер MCP
Провайдери контенту
Вхідний шлях контенту, реалізований в окремому пакеті Packages/content-providers (@churchapps/content-providers), а не в API. Кожен провайдер реалізує інтерфейс IProvider (src/interfaces.ts): browse, getPlaylist, getInstructions і хуки автентифікації. Провайдери самостійно реєструються у реєстрі типу Map (src/providers/registry.ts). Тут B1 є клієнтом OAuth: провайдер оголошує AuthType зі значенням none, oauth_pkce, device_flow або form_login, а спільні допоміжні модулі (OAuthHelper, DeviceFlowHelper, TokenHelper, ApiHelper) виконують на боці клієнта PKCE або потік пристрою із зовнішнім джерелом. Сьогодні постачаються одинадцять провайдерів, зокрема Planning Center, Dropbox, Life.Church, CBN, BibleProject, Jesus Film, Lessons.church і B1.church. Вони передають контент до FreePlay і застосунків B1. → Провайдер контенту FreePlay
Річні плани працюють через цей шлях. Видавець навчальних матеріалів (з дозволом lessons.edit) веде впорядковані послідовності тижнів 1/2/3 в адмін-панелі Lessons.church (таблиці yearPlans і yearPlanWeeks у LessonsApi, з необов'язковими startMonth і anchor для кожного тижня зі значеннями easter або christmas). GET /yearPlans/public у LessonsApi анонімно віддає чинні плани, заповнюючи програму, вивчення та місце для кожного тижня з дерева уроків. Розділ B1Admin Serving → Plans → Schedule Lesson → Apply Year Plan використовує цю кінцеву точку і записує один план DoingApi для кожного включеного тижня (providerId=lessonschurch, providerPlanId=/lessons/{programId}/{studyId}/{lessonId}/{venueId}). Плани з startMonth розв'язують прив'язані тижні відносно обраного року (Великдень за григоріанським обчисленням, Різдво як неділя, що припадає на 25 грудня або раніше) і заповнюють проміжки між ними. Плани без startMonth зіставляють тиждень N з датою startDate + (N−1)×7 днів. Тижні зовнішніх провайдерів OLF або з неповним шляхом пропускаються під час застосування. Церкви редагують створені плани так само, як і будь-які інші, а FreePlay відтворює те, що є в плані.
Підсумок
| Поверхня | Механізм автентифікації | Напрямок | Де реалізовано | Довідник |
|---|---|---|---|---|
| REST API | Bearer JWT або ключ cak_… | Вхідний | Api/src/modules/* | API-ключі |
| API-ключі | Токен cak_ з хешем SHA-256 | Облікові дані | Api/.../membership/controllers/ApiKeyController.ts | API-ключі |
| OAuth 2.0 / підключені застосунки | Код авторизації (PKCE) · пристрій · оновлення → JWT; динамічна реєстрація клієнтів | Вхідний | Api/.../membership/controllers/OAuthController.ts | Підключені застосунки |
| Вебхуки | Секрет для кожного хука, підпис HMAC-SHA256 | Вихідний | Api/src/shared/webhooks/ + WebhookController.ts | Вебхуки |
| Сервер MCP | Bearer JWT, JWT OAuth (знаходиться через /.well-known) або ключ cak_… | Вхідний (ШІ) | Api/src/modules/mcp/ | Сервер MCP |
| Провайдери контенту | Для кожного провайдера: немає / OAuth PKCE / пристрій / форма | Вхідний контент | Packages/content-providers/ | Провайдер контенту |
Готові з'єднувачі
Замість того щоб усі створювали рішення з нуля, ChurchApps постачає з'єднувачі, побудовані на описаних вище поверхнях:
- Slack і Discord —
connectorTypeвебхука перетворює стандартний конверт на повідомлення чату; налаштовується повністю в B1Admin без стороннього облікового запису. - Mailchimp —
connectorTypeзі значеннямmailchimpсинхронізує людей з аудиторією Mailchimp і зіставляє членство в групах і списках з тегами (Api/src/shared/webhooks/MailchimpConnector.ts). На відміну від чат-з'єднувачів, він надсилає власні автентифіковані запити для кожної події (оновлення, архівування, теги), замість POST-запиту на URL, наданий церквою. Ключ API та ідентифікатор аудиторії зберігаються в зашифрованому вигляді вwebhooks.connectorConfig. Синхронізація односторонья, лише стандартні поля злиття. - Zapier і Make — запускаються від подій вебхука та діють через REST API; самі реєструють свій вебхук, коли Zap або сценарій вмикається (потрібен ключ з
settings:write). Вихідний код застосунку Zapier знаходиться в репозиторіїIntegrationsу каталозіzapier/(CLI Zapier, розгортається командоюzapier push). - Google Sheets — доповнення з автентифікацією через ключ API, яке на вимогу експортує дані People, Donations, Groups та Attendance.
- Claude і ChatGPT — клієнти MCP, спрямовані на
/mcp.
Для власного коду @churchapps/integration-sdk (Packages/integration-sdk) об'єднує все це: типізований REST-клієнт, клієнт OAuth (код авторизації / оновлення / потік пристрою) і перевірку вебхуків HMAC з проміжним ПЗ для Express.
Пов'язані сторінки
- API-ключі — найпростіший обліковий запис і каталог областей доступу
- Підключені застосунки та OAuth — потоки погодження для багатокористувацьких застосунків
- Вебхуки — система вихідних подій
- Сервер MCP — ШІ-обгортка для інтеграції
- Провайдер контенту FreePlay — як стати вхідним джерелом контенту
- Інтеграції (для кінцевих користувачів) — посібники з налаштування готових з'єднувачів