Lumipat sa pangunahing nilalaman

Integrasyon at Extension Surface

Lahat ng maaaring ikabit ng third party ay dumadaan sa iisang API at iisang modelo ng awtorisasyon. Ang pahinang ito ang mapa: pinangangalanan nito ang bawat integration surface, ipinapakita kung paano sila nagkakaugnay, at nagli-link sa detalyadong reference ng bawat isa. Kung gumagawa ka laban sa B1, magsimula dito para piliin ang tamang pinto, at sundan ang link papunta sa pahinang nagdodokumento nito nang mas malalim.

Ang mga Surface sa Isang Sulyap​

May anim na paraan papasok o palabas, at lahat sila ay nagbabahagi ng iisang auth layer:

  • REST API: ang buong product surface, na maaaring tawagin gamit ang bearer token mula sa anumang wika.
  • API keys: ang pinakasimpleng credential, isang token na cak_… na nakatali sa isang tao sa isang simbahan.
  • OAuth 2.0 & Connected Apps: pahintulot ng simbahan kada simbahan para sa mga multi-tenant na app. Naglalabas ito ng parehong JWT na nakukuha ng isang user.
  • Webhooks: mga naka-sign at matibay na naihahatid na outbound na event.
  • MCP server: isang wrapper para sa AI sa ibabaw ng REST API, sa /mcp.
  • Content providers: ang inbound na daan para sa mga external na media library papunta sa FreePlay at sa mga B1 app.

Lahat maliban sa content providers ay inihahain ng iisang monolithic na API (ang repository na Api), at ang mga module nito ay nakakabit sa matatag na base path: /membership, /giving, /attendance, /content, /messaging, /doing, /reporting, at /mcp.

Paano Ito Nagkakasama​

   ┌─────────────────────┐                          ┌───────────────────────────────────────┐
│ 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)

Tatlong palaso ang nagsasalaysay ng buong kuwento: tumatawag papasok ang third party gamit ang bearer token (API key o OAuth JWT, kasama ang sa pamamagitan ng /mcp). Tumatawag palabas ang API sa pamamagitan ng mga naka-sign na webhook. At ang content providers ang iisang daan ng inbound na content kung saan ang B1 mismo ang OAuth client na kumukuha ng media mula sa external na pinagmulan.

Ang Shared Auth Model​

Bawat credential, maging ang login JWT ng user, ang OAuth access token, o ang API key, ay nireresolba sa parehong Principal at sinusuri sa parehong paraan. Walang hiwalay na "integration auth" path. Ang scoped na credential ay hindi nagkakaiba sa isang user na may mas mababang pribilehiyo.

Istruktura ng JWT​

Ang mga access token ng B1 ay mga HS256 JWT na ginawa sa Api/src/modules/membership/auth/AuthenticatedUser.ts. Ito ang hanay ng claim:

ClaimKahulugan
id, email, firstName, lastNameAng taong nasa likod ng token
churchIdAng iisang simbahan kung saan kumikilos ang token. Ito ang angkla ng lahat ng data scoping
personIdAng talaan ng tao sa loob ng simbahang iyon
permissionsPatag na array ng mga RBAC perm-string ([apiName_]contentType_contentId_action)
groupIds, leaderGroupIdsMembership at pamumuno sa group, para sa mga check na nakabatay sa group
membershipStatusGuest o miyembro, para sa pagbabantay ng self-service

Ang OAuth access token ay magkapareho ang hugis, byte-for-byte, sa login JWT. Ang tanging pagkakaiba ay na ang array nitong permissions ay sinala ayon sa mga ibinigay na scope bago pirmahan (getCombinedApiJwt(...)).

Scoping kada simbahan​

Ang churchId ay claim ng token, hindi parameter ng request, kaya hindi kailanman makakarating ang isang credential sa ibang simbahan. Sinasala ng bawat repository query ang churchId ng tumatawag. Nakatali ang API key o OAuth token sa eksaktong isang simbahan sa oras ng paglikha nito.

Mga pahintulot na nakabatay sa tungkulin sa hangganan​

Ginagating ng mga controller ang mga aksyon gamit ang au.checkAccess(contentType, action) laban sa array ng permissions ng token. Ang mga scope ay isang filter, hindi grant (Api/src/shared/auth/Scopes.ts). Ang SCOPE_CATALOG ay nagmamapa ng bawat scope (halimbawa people:read, donations:write) sa mga pares ng RBAC na pinapayagan nito. Ang filterPermissionsByScopes() ay nag-iintersect nito sa kasalukuyang pahintulot ng tao sa bawat resolve. Ang mga kahihinatnan:

  • Kapag binawi ang isang pahintulot sa B1Admin, puputulin ang access ng credential sa susunod na request. Hindi kailanman lumilihis ang mga token sa tungkulin.
  • Ang scope ay maaari lamang mag-alis ng pahintulot, kaya hindi kailanman makakataas ang isang scoped na credential sa pagiging server o domain administrator. Sinadyang hindi naka-map sa anumang scope ang mga pahintulot na iyon.
  • May prefix na cak_ ang mga API key. Sinusuri ng CustomAuthProvider.getUser() ang prefix na ito, hina-hash ang secret, at muling nireresolba ang live na RBAC ng nagmamay-ari na tao sa bawat tawag.

Tingnan ang API Keys → Scopes para sa buong catalog ng scope.

Reference ng Surface​

REST API​

Ang buong product surface. Tumatanggap ang anumang naka-authenticate na endpoint ng alinman sa JWT o API key na cak_… sa header na Authorization: Bearer. Walang hiwalay na route table para sa key-lamang o OAuth-lamang. Ang mga module at ang kanilang base path ay nasa ilalim ng Api/src/modules/*.

API keys​

Isang personal access token na cak_<prefix>.<secret>, na nililikha sa B1Admin → Settings → Developer → API Keys. Ang SHA-256 hash lamang ang iniimbak. Ipinapakita nang minsan lang ang raw na key. Pinamamahalaan sa /membership/apiKeys (Api/src/modules/membership/controllers/ApiKeyController.ts). Pinakamainam para sa mga script ng iisang simbahan at para sa mga connector gaya ng Zapier, Make, at Google Sheets. → API Keys

OAuth 2.0 & Connected Apps​

Para sa mga multi-tenant na app na nangangailangan ng pahintulot ng bawat simbahan. Ipinatutupad sa Api/src/modules/membership/controllers/OAuthController.ts sa ilalim ng /membership/oauth. Tatlong grant ang sinusuportahan ng server:

  • Authorization Code: ang POST /oauth/authorize (naka-authenticate) ay nagbabalik ng maikling-buhay na code. Ang POST /oauth/token na may grant_type=authorization_code ay nagpapalit nito sa access JWT (≈ 7 araw) at refresh token (≈ 90 araw). Kailangang gumamit ng PKCE (S256 lamang) ang mga public na client (walang secret): isang code_challenge sa authorize at ang tugmang code_verifier sa palitan ng token.
  • Device Code (RFC 8628): ang POST /oauth/device/authorize ay naglalabas ng user_code. Inaaprubahan ito ng user sa B1Admin (/oauth/device/approve), at ang device ay nagpo-poll sa /oauth/token gamit ang device-code grant. Para sa mga TV, kiosk, at CLI na walang browser.
  • Refresh Token: ang grant_type=refresh_token ay naglalabas ng bagong access token. Maaaring hindi magpadala ng secret ang mga public na client (walang secret).

Maaaring magparehistro ang mga public na client sa sarili nila gamit ang POST /oauth/register (RFC 7591 dynamic client registration). Nakakakuha sila ng client_id at walang secret, at dapat na https o loopback ang kanilang redirect URI.

Ang Connected App ay ang pagtingin ng admin ng simbahan sa isang ipinagkaloob na token. Nakalista ito at nababawi sa /membership/oauth/connections. Naglalaman din ang controller ng OAuth relay-session bridge (/oauth/relay/*) na nagpapahintulot sa isang device na walang browser na mag-sign in sa isang external na provider. → Connected Apps & OAuth

Webhooks​

Ang tanging outbound na surface. Nagsa-subscribe ang isang simbahan ng pampublikong HTTPS endpoint sa mga event. Kapag may tugmang pagbabago, ang WebhookDispatcher.emit(churchId, event, payload) ay nagdaragdag ng mga display name sa mga payload na id lamang (personName, groupName, formName; tumatakbo lamang ang mga lookup kapag may tugmang subscription). Nagtatala ito ng delivery, at isang background worker ang nagpo-POST ng naka-sign na JSON envelope na may retry/backoff at redelivery. Ang engine ay nasa Api/src/shared/webhooks/, at ang CRUD kada simbahan ay nasa ilalim ng /membership/webhooks (WebhookController.ts). Binabago ng field na connectorType ang hugis ng body para sa Slack / Discord. Mas malayo ang narating ng connector na mailchimp: sarili nitong pinamamahalaan ang buong HTTP exchange (method/URL/auth kada event laban sa API ng Mailchimp, at naka-encrypt ang mga credential sa webhooks.connectorConfig). → Webhooks

MCP server​

Isang AI-facing na wrapper sa /mcp (Api/src/modules/mcp/). Tatlong pangkalahatang tool ang naglalantad ng buong REST surface nang dinamiko sa anumang MCP client: list_endpoints, describe_endpoint, at api_call. Pareho ang auth, ang parehong bearer token gaya ng lahat ng iba. Para sa mga client na nag-sign in gamit ang OAuth (claude.ai custom connectors), ang 401 mula sa /mcp ay may header na WWW-Authenticate na tumuturo sa /.well-known/oauth-protected-resource. Ang /.well-known/oauth-authorization-server ay nag-aanunsyo ng mga endpoint ng /membership/oauth, dynamic registration, PKCE, at ang consent page ng /oauth sa B1Admin (WellKnownController.ts, OAuthMetadata.ts). Muling pumapasok ang api_call sa Express stack sa loob ng proseso, kaya nananatiling ipinatutupad ang bawat patakaran ng pahintulot at scoping ng simbahan. → MCP Server

Content providers​

Ang inbound na daan ng content, sa hiwalay na package na Packages/content-providers (@churchapps/content-providers) at hindi sa API. Ang bawat provider ay nagpapatupad ng interface na IProvider (src/interfaces.ts): browse, getPlaylist, getInstructions, at mga auth hook. Nagrerehistro ito ng sarili sa isang Map registry (src/providers/registry.ts). Dito, ang B1 ang OAuth client. Nagdedeklara ang provider ng AuthType na none, oauth_pkce, device_flow, o form_login. Pinapatakbo ng mga shared helper (OAuthHelper, DeviceFlowHelper, TokenHelper, ApiHelper) ang PKCE / device flow sa panig ng client laban sa external na pinagmulan. Labing-isang provider ang kasalukuyang ipinapadala, kabilang ang Planning Center, Dropbox, Life.Church, CBN, BibleProject, Jesus Film, Lessons.church, at B1.church. Pinapakain nila ang FreePlay at ang mga B1 app. → FreePlay Content Provider

Ang mga year plan ay dumadaan din sa daang ito. Ang isang publisher ng kurikulum (na may lessons.edit) ay nagpapanatili ng mga nakaayos na sunod-sunod na week-1/2/3 sa admin ng Lessons.church (mga table ng LessonsApi na yearPlans / yearPlanWeeks, na may opsyonal na startMonth at anchor kada linggo na easter o christmas). Inihahain ng GET /yearPlans/public sa LessonsApi ang mga live na plano nang anonymous. Hinihydrate nito ang program/study/venue ng bawat linggo mula sa lesson tree. Ginagamit ng Serving → Plans → Schedule Lesson → Apply Year Plan ng B1Admin ang endpoint na ito at sumusulat ng isang DoingApi plan kada kasamang linggo (providerId=lessonschurch, providerPlanId=/lessons/{programId}/{studyId}/{lessonId}/{venueId}). Para sa mga plano na may startMonth, nireresolba ang mga naka-anchor na linggo laban sa napiling taon (Easter sa pamamagitan ng Gregorian computus, Christmas bilang ang Linggo sa o bago ng Dis. 25), at pinupunan ang mga agwat sa pagitan nila. Ang mga plano na walang startMonth ay nagmamapa pa rin ng linggo N sa startDate + (N−1)×7 na araw. Nilalaktawan sa oras ng pag-apply ang mga linggong galing sa external na OLF provider o may hindi kumpletong path. Ini-e-edit ng mga simbahan ang nagresultang mga plano na parang iba pang plano, at ang FreePlay ay tumutugtog ng kung ano man ang nasa plano.

Buod​

SurfaceMekanismo ng authDireksyonSaan ipinatutupadReference
REST APIBearer JWT o cak_… keyPapasokApi/src/modules/*API Keys
API keysToken na cak_ na may SHA-256 hashCredentialApi/.../membership/controllers/ApiKeyController.tsAPI Keys
OAuth 2.0 / Connected AppsAuth code (PKCE) · device · refresh → JWT; dynamic client registrationPapasokApi/.../membership/controllers/OAuthController.tsConnected Apps
WebhooksSecret kada hook, HMAC-SHA256 signaturePalabasApi/src/shared/webhooks/ + WebhookController.tsWebhooks
MCP serverBearer JWT, OAuth JWT (natutuklasan sa pamamagitan ng /.well-known), o cak_… keyPapasok (AI)Api/src/modules/mcp/MCP Server
Content providersDepende sa provider: wala / OAuth PKCE / device / formPapasok na contentPackages/content-providers/Content Provider

Mga Prebuilt na Connector​

Sa halip na gumawa ng lahat mula sa simula, nagbibigay ang ChurchApps ng mga connector sa ibabaw ng mga surface sa itaas:

  • Slack & Discord: ang webhook na connectorType ay humuhubog sa karaniwang envelope bilang chat message. Ganap na naka-configure sa B1Admin, walang third-party na account na kailangan.
  • Mailchimp: isang connectorType na mailchimp na nagsi-sync ng mga tao sa isang Mailchimp audience at minamapa ang membership ng group/list sa mga tag (Api/src/shared/webhooks/MailchimpConnector.ts). Hindi tulad ng mga chat connector, sarili nitong nagpapadala ng mga authenticated na request kada event (upsert/archive/tag) sa halip na mag-POST sa URL na ibinigay ng simbahan. Naka-encrypt na nakaimbak sa webhooks.connectorConfig ang API key at audience id. Isang direksyon lamang, at karaniwang merge field lamang.
  • Zapier at Make: nagti-trigger sa mga webhook event at kumikilos sa pamamagitan ng REST API. Nagrerehistro sila ng sarili nilang webhook kapag na-on ang isang Zap o scenario (kailangan ng key na may settings:write). Ang source ng Zapier app ay nasa repository na Integrations sa ilalim ng zapier/ (Zapier CLI, dine-deploy gamit ang zapier push).
  • Google Sheets: isang add-on na naka-authenticate gamit ang API key na nag-e-export ng People / Donations / Groups / Attendance kapag hiniling.
  • Claude at ChatGPT: mga MCP client na nakaturo sa /mcp.

Para sa sarili mong code, binabalot ng @churchapps/integration-sdk (Packages/integration-sdk) ang lahat ng ito: isang typed na REST client, isang OAuth client (auth-code / refresh / device flow), at isang HMAC webhook verifier na may Express middleware.

Mga Kaugnay na Pahina​