Ugrás a fő tartalomra

Integrációs és bővítési felület

Minden, amit harmadik fél csatlakoztathat, egyetlen API-n és egyetlen jogosultsági modellen keresztül működik. Ez az oldal térkép: megnevezi az összes integrációs felületet, bemutatja, hogyan kapcsolódnak egymáshoz, és mindegyikhez a részletes leírásra hivatkozik. Ha B1-re fejlesztesz, itt kezdj, válaszd ki a megfelelő bejáratot, majd kövesd a hivatkozást a részletesen dokumentált oldalra.

A felületek áttekintése​

Hat bejárat van be és ki, és mindegyik ugyanazt a hitelesítési réteget használja:

  • REST API — a teljes termékfelület, amely bármely nyelvről hívható bearer tokennel.
  • API-kulcsok — a legegyszerűbb hitelesítő adat: egy cak_… token, amely egy személyhez és egy gyülekezethez kötött.
  • OAuth 2.0 és csatlakoztatott alkalmazások — gyülekezetenkénti hozzájárulás többbérlős alkalmazásokhoz; ugyanazt a JWT-t adja ki, mint amit a felhasználó kap.
  • Webhookok — aláírt, tartósan kézbesített kimenő események.
  • MCP-szerver — AI-barát burkoló a REST API fölött a /mcp útvonalon.
  • Tartalomszolgáltatók — a külső médiatárak bejövő útja a FreePlay-be és a B1 alkalmazásokba.

A tartalomszolgáltatók kivételével minden egyetlen monolitikus API-n keresztül érhető el (az Api tárolóban), amelynek moduljai stabil alap útvonalak alatt csatlakoznak: /membership, /giving, /attendance, /content, /messaging, /doing, /reporting és /mcp.

Hogyan illeszkedik össze​

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

Három nyíl mondja el a teljes történetet: egy harmadik fél egy bearer tokennel hív be (API-kulcs vagy OAuth JWT, többek között a /mcp útvonalon keresztül); az API aláírt webhookokon keresztül visszahív; a tartalomszolgáltatók pedig az egyetlen bejövő tartalmi útvonal, ahol maga a B1 az OAuth kliens, amely médiát húz le egy külső forrásból.

A közös hitelesítési modell​

Minden hitelesítő adat (a felhasználó bejelentkezési JWT-je, egy OAuth hozzáférési token vagy egy API-kulcs) ugyanarra a Principal-ra oldódik fel, és ugyanúgy ellenőrződik. Nincs külön „integrációs hitelesítési” út; egy hatókörrel korlátozott hitelesítő adat egyszerűen megkülönböztethetetlen egy alacsonyabb jogosultságú felhasználótól.

JWT szerkezete​

A B1 hozzáférési tokenjei HS256 JWT-k, amelyeket az Api/src/modules/membership/auth/AuthenticatedUser.ts állít ki. A claim-készlet:

ClaimJelentés
id, email, firstName, lastNameA tokent birtokló személy
churchIdAz egyetlen gyülekezet, amelyen belül ez a token működik; minden adatkezelés alapja
personIdA személy rekordja abban a gyülekezetben
permissionsLapos RBAC jogosultsági karakterlánc-tömb ([apiName_]contentType_contentId_action)
groupIds, leaderGroupIdsCsoporttagság és csoportvezetés, csoport-hatókörű ellenőrzésekhez
membershipStatusVendég vagy tag, az önkiszolgáló korlátozásokhoz

Az OAuth hozzáférési token bájtra pontosan ugyanolyan alakú, mint a bejelentkezési JWT. Az egyetlen különbség, hogy a permissions tömböt a kiállítás előtt a megadott hatókörökön szűrték (getCombinedApiJwt(...)).

Gyülekezetenkénti hatókör​

A churchId token-claim, nem kérésparaméter, így egy hitelesítő adat soha nem érhet el más gyülekezeteket. Minden tárolólekérdezés a hívó churchId-jára szűr; egy API-kulcs vagy OAuth token a kiállításkor pontosan egy gyülekezethez kötődik.

Szerepalapú jogosultságok a határon​

A vezérlők a au.checkAccess(contentType, action) hívással kapuznak a token permissions tömbjével szemben. A hatókörök szűrők, sosem jogosultságadók (Api/src/shared/auth/Scopes.ts): a SCOPE_CATALOG minden hatókört (pl. people:read, donations:write) a megengedett RBAC párokhoz rendel, a filterPermissionsByScopes() pedig ezt metszi a személy minden feloldáskor aktuális jogosultságaival. Ennek következményei:

  • A B1Admin-ban visszavont jogosultság a következő kérésnél megszünteti a hitelesítő adat hozzáférését; a tokenek soha nem térnek el a szerepkörtől.
  • Egy hatókör csak jogosultságokat távolíthat el, így a hatókörrel korlátozott hitelesítő adat nem emelkedhet szerver- vagy domain-adminisztrátori szintre (ezek a jogosultságok szándékosan nincsenek hatókörhöz rendelve).
  • Az API-kulcsok cak_ előtaggal rendelkeznek; a CustomAuthProvider.getUser() ezt ellenőrzi, hashelja a titkot, és minden hívásnál újra feloldja a tulajdonos személy aktuális RBAC-jogosultságait.

A teljes katalógusért lásd: API-kulcsok → Hatókörök.

Felületi referencia​

REST API​

A teljes termékfelület. Bármely hitelesített végpont elfogad JWT-t vagy cak_… API-kulcsot az Authorization: Bearer fejlécben. Nincs külön csak-kulcsos vagy csak-OAuth útvonaltábla. A modulok és alap útvonalaik az Api/src/modules/* alatt találhatók.

API-kulcsok​

Egy cak_<prefix>.<secret> személyes hozzáférési token, amelyet a B1Admin → Settings → Developer → API Keys menüpontban lehet létrehozni. Csak egy SHA-256 hash tárolódik; a nyers kulcs egyszer jelenik meg. Kezelése a /membership/apiKeys alatt történik (Api/src/modules/membership/controllers/ApiKeyController.ts). Egy gyülekezet saját szkriptjeihez, illetve olyan összekötőkhöz legjobb, mint a Zapier, a Make és a Google Sheets. → API-kulcsok

OAuth 2.0 és csatlakoztatott alkalmazások​

Többbérlős alkalmazásokhoz, amelyeknek minden gyülekezet hozzájárulására szükségük van. A Api/src/modules/membership/controllers/OAuthController.ts fájlban valósul meg a /membership/oauth alatt. A szerver három engedélyezési típust támogat:

  • Authorization Code: a POST /oauth/authorize (hitelesítve) rövid életű kódot ad vissza; a POST /oauth/token a grant_type=authorization_code paraméterrel ezt egy hozzáférési JWT-re (kb. 7 nap) és egy frissítő tokenre (kb. 90 nap) váltja. A nyilvános (titok nélküli) kliensnek PKCE-t kell használnia (kizárólag S256): egy code_challenge az authorize hívásnál, és a megfelelő code_verifier a token-cseréhez.
  • Device Code (RFC 8628): a POST /oauth/device/authorize egy user_code-ot ad ki; a felhasználó ezt a B1Admin-ban hagyja jóvá (/oauth/device/approve); az eszköz az /oauth/token végpontot kérdezi le az eszközkód-engedéllyel. TV-khez, kioszkokhoz és böngésző nélküli CLI-khez való.
  • Frissítő token: a grant_type=refresh_token új hozzáférési tokent ad ki; a nyilvános (titok nélküli) kliensek elhagyhatják a titkot.

A nyilvános kliensek a POST /oauth/register végponton (RFC 7591 dinamikus kliensregisztráció) maguk is regisztrálhatják magukat. Ilyenkor client_id-t kapnak titok nélkül, átirányítási URI-jaiknak pedig https vagy loopback típusúnak kell lenniük.

A csatlakoztatott alkalmazás a gyülekezeti adminisztrátor számára látható nézete egy megadott tokennek; a /membership/oauth/connections alatt listázható és visszavonható. A vezérlő egy OAuth relay-session hidat is tartalmaz (/oauth/relay/*), amely lehetővé teszi, hogy egy böngésző nélküli eszköz egy külső szolgáltatónál fejezze be a bejelentkezést. → Csatlakoztatott alkalmazások és OAuth

Webhookok​

Az egyetlen kimenő felület. Egy gyülekezet nyilvános HTTPS-végpontot iratkoztat fel eseményekre. Amikor egyező változás történik, a WebhookDispatcher.emit(churchId, event, payload) az csak azonosítót tartalmazó adatokat megjelenítendő nevekkel egészíti ki (personName, groupName, formName; a keresések csak akkor futnak, ha egy feliratkozás egyezik). Rögzít egy kézbesítést, a háttérfolyamat pedig aláírt JSON-borítékot küld POST-tal, újrapróbálkozással és visszalépéssel (backoff). A motor a Api/src/shared/webhooks/ alatt van, a gyülekezetenkénti CRUD a /membership/webhooks alatt (WebhookController.ts). A connectorType mező átformálja a törzset Slack- és Discord-üzenetekhez. A mailchimp összekötő tovább megy: a teljes HTTP-cserét maga kezeli (eseményenkénti metódus, URL és hitelesítés a Mailchimp API-ja felé; a hitelesítő adatok titkosítva a webhooks.connectorConfig mezőben). → Webhookok

MCP-szerver​

Egy AI-barát burkoló a /mcp alatt (Api/src/modules/mcp/). Három általános eszköz (list_endpoints, describe_endpoint, api_call) dinamikusan teszi elérhetővé a teljes REST-felületet bármely MCP-kliens számára. A hitelesítés ugyanaz a bearer token, mint mindenhol máshol. Az OAuth-tal bejelentkező kliensek (claude.ai egyedi összekötők) számára a /mcp 401-es válasza WWW-Authenticate fejlécet tartalmaz, amely a /.well-known/oauth-protected-resource címre mutat. A /.well-known/oauth-authorization-server hirdeti a /membership/oauth végpontokat, a dinamikus regisztrációt, a PKCE-t és a B1Admin /oauth hozzájárulási oldalt (WellKnownController.ts, OAuthMetadata.ts). Az api_call folyamatban újra belép az Express-verembe, így minden jogosultsági és gyülekezeti hatókör-szabály továbbra is érvényes. → MCP-szerver

Tartalomszolgáltatók​

A bejövő tartalmi út a külön Packages/content-providers csomagban van (@churchapps/content-providers), nem az API-ban. Minden szolgáltató megvalósítja az IProvider interfészt (src/interfaces.ts): browse, getPlaylist, getInstructions, valamint hitelesítési horgok. Saját magát egy Map regisztrációs táblába (src/providers/registry.ts) jegyzi be. Itt a B1 az OAuth-kliens: a szolgáltató AuthType típust deklarál (none, oauth_pkce, device_flow vagy form_login), a megosztott segédek (OAuthHelper, DeviceFlowHelper, TokenHelper, ApiHelper) pedig kliensoldali PKCE- vagy eszközfolyamatot futtatnak a külső forrással. Jelenleg tizenegy szolgáltató érhető el, köztük a Planning Center, a Dropbox, a Life.Church, a CBN, a BibleProject, a Jesus Film, a Lessons.church és a B1.church. Ezek a FreePlay-nek és a B1 alkalmazásoknak szolgáltatnak tartalmat. → FreePlay tartalomszolgáltató

Évtervek erre az útvonalra épülnek. Egy tananyag-kiadó (lessons.edit jogosultsággal) a Lessons.church adminisztrációjában tart fenn rendezett 1., 2. és 3. heti sorozatokat (a LessonsApi yearPlans és yearPlanWeeks táblái, opcionális startMonth mezővel és heti anchor értékkel: easter vagy christmas). A LessonsApi GET /yearPlans/public végpontja névtelenül szolgálja ki az élő terveket, és minden hét program-, tanulmány- és helyszíninformációját a leckefából tölti fel. A B1Admin Serving → Plans → Schedule Lesson → Apply Year Plan menüpontja ezt a végpontot használja, és minden szerepeltetett hétre egy DoingApi-tervet ír (providerId=lessonschurch, providerPlanId=/lessons/{programId}/{studyId}/{lessonId}/{venueId}). A startMonth mezővel rendelkező tervek a horgonyzott heteket a kiválasztott évhez igazítják (húsvét a gregorián számítással, karácsony az év december 25-ét megelőző vagy arra eső vasárnapja), és kitöltik a köztük lévő időszakokat. A startMonth nélküli tervek továbbra is az N. hetet startDate + (N−1)×7 napraképezik le. A külső OLF-szolgáltatók heteit, illetve a hiányos útvonallal rendelkezőket az alkalmazáskor kihagyja a rendszer. A gyülekezetek a létrejövő terveket úgy szerkeszthetik, mint bármely mást, a FreePlay pedig azt játssza le, ami a tervben van.

Összefoglalás​

FelületHitelesítési mechanizmusIrányMegvalósítás helyeReferencia
REST APIBearer JWT vagy cak_… kulcsBejövőApi/src/modules/*API-kulcsok
API-kulcsokSHA-256-tal hashelt cak_ tokenHitelesítő adatApi/.../membership/controllers/ApiKeyController.tsAPI-kulcsok
OAuth 2.0 / csatlakoztatott alkalmazásokEngedélyezési kód (PKCE) · eszköz · frissítés → JWT; dinamikus kliensregisztrációBejövőApi/.../membership/controllers/OAuthController.tsCsatlakoztatott alkalmazások
WebhookokHookonkénti titok, HMAC-SHA256 aláírásKimenőApi/src/shared/webhooks/ + WebhookController.tsWebhookok
MCP-szerverBearer JWT, OAuth JWT (/.well-known útján felfedezve) vagy cak_… kulcsBejövő (AI)Api/src/modules/mcp/MCP-szerver
TartalomszolgáltatókSzolgáltatónként: nincs / OAuth PKCE / eszköz / űrlapBejövő tartalomPackages/content-providers/Tartalomszolgáltató

Előre elkészített összekötők​

Ahelyett, hogy mindenki nulláról építene, a ChurchApps összekötőket szállít a fenti felületekre:

  • Slack és Discord — a webhook connectorType a szabványos borítékot csevegőüzenetté alakítja. Teljes egészében a B1Admin-ban konfigurálható, harmadik féltől származó fiók nélkül.
  • Mailchimp — a mailchimp connectorType személyeket szinkronizál egy Mailchimp-közönségbe, és a csoport- és listatagságot címkékre képezi (Api/src/shared/webhooks/MailchimpConnector.ts). A chat-összekötőkkel ellentétben minden eseményhez saját hitelesített kéréseket küld (feltöltés, archiválás, címkézés), nem pedig a gyülekezet által megadott URL-re POST-ol. Az API-kulcs és a közönség-azonosító titkosítva a webhooks.connectorConfig mezőben tárolódik. Egyirányú, csak a szabványos összevonási mezőket használja.
  • Zapier és Make: webhook-eseményekre indulnak, és a REST API-n keresztül cselekszenek. Amikor egy Zap vagy forgatókönyv bekapcsol, saját webhookot regisztrálnak (settings:write jogosultságú kulcs szükséges). A Zapier-alkalmazás forráskódja az Integrations tároló zapier/ mappájában található (Zapier CLI, telepítés zapier push paranccsal).
  • Google Sheets: API-kulccsal hitelesített bővítmény, amely igény szerint exportálja a Személyeket, Adományokat, Csoportokat és Részvételt.
  • Claude és ChatGPT: a /mcp végpontra mutató MCP-kliensek.

Saját kódodhoz a @churchapps/integration-sdk (Packages/integration-sdk) mindezt becsomagolja: egy típusos REST-klienst, egy OAuth-klienst (engedélyezési kód, frissítés, eszközfolyamat) és egy HMAC webhook-ellenőrzőt Express middleware-rel.

Kapcsolódó oldalak​