Přejít na hlavní obsah

Integrační a rozšiřující plocha

Vše, co se může třetí strana připojit, prochází jedním API a jedním autorizačním modelem. Tato stránka je mapa: pojmenovává každou integrační plochu, ukazuje, jak spolu souvisejí, a odkazuje na podrobnou referenci ke každé z nich. Pokud vytváříte něco nad B1, začněte zde, vyberte správné rozhraní a pokračujte odkazem na stránku, která ho popisuje do hloubky.

Přehled ploch​

Existuje šest způsobů, jak dovnitř a ven, a všechny sdílejí stejnou autentizační vrstvu:

  • REST API — celý produktový povrch, volatelný s bearer tokenem z jakéhokoli jazyka.
  • API klíče — nejjednodušší přihlašovací údaj: token cak_… vázaný na jednu osobu v jednom sboru.
  • OAuth 2.0 a propojené aplikace — souhlas na úrovni sboru pro vícenájemcové aplikace; vydává stejný JWT, jaký dostane uživatel.
  • Webhooky — podepsané, trvale doručované odchozí události.
  • MCP server — wrapper nad REST API určený pro AI na /mcp.
  • Poskytovatelé obsahu — příchozí cesta pro externí mediální knihovny do FreePlay a aplikací B1.

Vše kromě poskytovatelů obsahu obsluhuje jediné monolitické API (repozitář Api), jehož moduly jsou připojeny pod stabilními základními cestami — /membership, /giving, /attendance, /content, /messaging, /doing, /reporting a /mcp.

Jak to spolu souvisí​

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

Tři šipky vyprávějí celý příběh: třetí strana volá dovnitř s bearer tokenem (API klíč nebo OAuth JWT, včetně přes /mcp); API volá zpět ven přes podepsané webhooky; a poskytovatelé obsahu jsou jedinou příchozí cestou obsahu, kde je sám B1 OAuth klientem a stahuje média z externího zdroje.

Sdílený autentizační model​

Každý přihlašovací údaj — přihlašovací JWT uživatele, OAuth přístupový token nebo API klíč — se přeloží na stejný Principal a kontroluje se stejným způsobem. Neexistuje žádná oddělená „integrační autentizace“; omezený přihlašovací údaj je prostě nerozeznatelný od uživatele s nižšími oprávněními.

Struktura JWT​

Přístupové tokeny B1 jsou HS256 JWT vydávané v Api/src/modules/membership/auth/AuthenticatedUser.ts. Sada claimů:

ClaimVýznam
id, email, firstName, lastNameOsoba, ke které token patří
churchIdJediný sbor, v jehož rámci tento token jedná — kotva pro veškeré určování rozsahu dat
personIdZáznam osoby uvnitř daného sboru
permissionsPlochý pole řetězců oprávnění RBAC ([apiName_]contentType_contentId_action)
groupIds, leaderGroupIdsČlenství ve skupinách / vedení skupin, pro kontroly v rámci skupiny
membershipStatusHost vs. člen, pro řízení samoobsluhy

OAuth přístupový token má přesně stejný tvar jako přihlašovací JWT — jediný rozdíl je v tom, že jeho pole permissions bylo před podepsáním přefiltrováno přes udělené rozsahy (getCombinedApiJwt(...)).

Určování rozsahu podle sboru​

churchId je claim tokenu, nikoli parametr požadavku, takže přihlašovací údaj nikdy nemůže zasáhnout do jiných sborů. Každý dotaz do repozitáře filtruje podle churchId volajícího; API klíč nebo OAuth token je vázán přesně na jeden sbor v okamžiku vydání.

Oprávnění založená na rolích na hranici​

Kontrolery omezují akce voláním au.checkAccess(contentType, action) proti poli permissions tokenu. Rozsahy jsou filtr, nikoli udělení (Api/src/shared/auth/Scopes.ts): SCOPE_CATALOG mapuje každý rozsah (např. people:read, donations:write) na dvojice RBAC, které povoluje, a filterPermissionsByScopes() provádí průnik s aktuálními oprávněními osoby při každém ověření. Důsledky:

  • Odebrání oprávnění v B1Admin odebere přístup přihlašovacímu údaji při dalším požadavku — tokeny se nikdy neodchylují od role.
  • Rozsah může oprávnění pouze odebírat, takže omezený přihlašovací údaj nikdy nemůže povýšit na správce serveru nebo domény (tato oprávnění jsou záměrně nenamapována na žádný rozsah).
  • API klíče nesou prefix cak_; CustomAuthProvider.getUser() se podle něj větví, hashuje tajemství a při každém volání znovu načte aktuální oprávnění RBAC vlastnící osoby.

Úplný katalog rozsahů viz API klíče → Rozsahy.

Přehled referencí ploch​

REST API​

Kompletní produktový povrch. Jakýkoli ověřený endpoint přijímá buď JWT, nebo cak_… API klíč v hlavičce Authorization: Bearer — neexistuje samostatná tabulka tras pouze pro klíče nebo pouze pro OAuth. Moduly a jejich základní cesty leží pod Api/src/modules/*.

API klíče​

Osobní přístupový token cak_<prefix>.<secret>, vytvořený v B1Admin → Nastavení → Vývojář → API klíče. Ukládá se pouze hash SHA-256; surový klíč se zobrazí jednou. Spravuje se na /membership/apiKeys (Api/src/modules/membership/controllers/ApiKeyController.ts). Nejvhodnější pro vlastní skripty jednoho sboru a pro konektory jako Zapier, Make a Google Sheets. → API klíče

OAuth 2.0 a propojené aplikace​

Pro vícenájemcové aplikace, které potřebují souhlas každého sboru. Implementováno v Api/src/modules/membership/controllers/OAuthController.ts pod /membership/oauth. Server podporuje tři granty:

  • Authorization Code — POST /oauth/authorize (ověřený) vrátí krátkodobý kód; POST /oauth/token s grant_type=authorization_code jej vymění za přístupový JWT (přibližně 7 dní) a refresh token (přibližně 90 dní). Veřejní klienti bez tajemství musí použít PKCE (pouze S256): code_challenge při autorizaci a odpovídající code_verifier při výměně tokenu.
  • Device Code (RFC 8628) — POST /oauth/device/authorize vydá user_code; uživatel jej schválí v B1Admin (/oauth/device/approve); zařízení dotazuje /oauth/token s grantem device-code. Určeno pro TV, kiosky a CLI bez prohlížeče.
  • Refresh Token — grant_type=refresh_token vydá nový přístupový token; veřejní klienti bez tajemství mohou tajemství vynechat.

Veřejní klienti se mohou také sami registrovat přes POST /oauth/register (dynamická registrace klienta podle RFC 7591); dostanou client_id bez tajemství a jejich redirect URI musí být https nebo loopback.

Propojená aplikace je pohled na udělený token z pohledu správce sboru; seznam a možnost odvolání je na /membership/oauth/connections. Kontroler také hostuje most relay-session OAuth (/oauth/relay/*), který umožňuje zařízení bez prohlížeče dokončit přihlášení proti externímu poskytovateli. → Propojené aplikace a OAuth

Webhooky​

Jediná odchozí plocha. Sbor přihlásí k odběru událostí veřejný HTTPS endpoint; když nastane odpovídající změna, WebhookDispatcher.emit(churchId, event, payload) obohatí payloady obsahující pouze ID o zobrazovaná jména (personName, groupName, formName — vyhledávání proběhne jen tehdy, když se odběr shoduje), zaznamená doručení a na pozadí worker odešle podepsanou JSON obálku s opakováním, backoffem a opětovným doručením. Engine je v Api/src/shared/webhooks/, CRUD pro každý sbor pod /membership/webhooks (WebhookController.ts). Pole connectorType přetváří tělo pro Slack a Discord; konektor mailchimp jde dál a vlastní celou HTTP výměnu (metoda, URL a autentizace pro každou událost vůči API Mailchimpu; přihlašovací údaje jsou šifrované v webhooks.connectorConfig). → Webhooky

MCP server​

AI wrapper na /mcp (Api/src/modules/mcp/). Tři generické nástroje — list_endpoints, describe_endpoint, api_call — dynamicky zpřístupňují celou REST plochu jakémukoli MCP klientovi. Autentizace je stejný bearer token jako u všeho ostatního. Pro klienty, kteří se přihlašují přes OAuth (vlastní konektory claude.ai), nese odpověď 401 z /mcp hlavičku WWW-Authenticate ukazující na /.well-known/oauth-protected-resource, a /.well-known/oauth-authorization-server inzeruje endpointy /membership/oauth, dynamickou registraci, PKCE a stránku souhlasu B1Admin /oauth (WellKnownController.ts, OAuthMetadata.ts). api_call znovu vstupuje do Express zásobníku in-process, takže se uplatní každé pravidlo oprávnění a určování rozsahu podle sboru. → MCP server

Poskytovatelé obsahu​

Příchozí cesta obsahu je v samostatném balíčku Packages/content-providers (@churchapps/content-providers), nikoli v API. Každý poskytovatel implementuje rozhraní IProvider (src/interfaces.ts) — browse, getPlaylist, getInstructions a háčky autentizace — a sám se registruje do registru Map (src/providers/registry.ts). Zde je B1 OAuth klientem: poskytovatel deklaruje AuthType jako none, oauth_pkce, device_flow nebo form_login a sdílené pomocné funkce (OAuthHelper, DeviceFlowHelper, TokenHelper, ApiHelper) provádějí na straně klienta PKCE nebo device flow vůči externímu zdroji. Dnes je dodáváno jedenáct poskytovatelů — včetně Planning Center, Dropbox, Life.Church, CBN, BibleProject, Jesus Film, Lessons.church a B1.church — které napájejí FreePlay a aplikace B1. → FreePlay poskytovatel obsahu

Plány na rok využívají tuto cestu. Autor kurikula (s oprávněním lessons.edit) udržuje uspořádané sekvence týdne 1/2/3 v administraci Lessons.church (tabulky LessonsApi yearPlans a yearPlanWeeks, s volitelným startMonth a per-týdenní anchor easter nebo christmas). GET /yearPlans/public na LessonsApi doručuje živé plány anonymně a u každého týdne doplní program, studii a místo ze stromu lekcí. V B1Admin → Servírování → Plány → Naplánovat lekci → Použít plán na rok se tento endpoint použije a zapíše se jeden plán DoingApi na každý zahrnutý týden (providerId=lessonschurch, providerPlanId=/lessons/{programId}/{studyId}/{lessonId}/{venueId}). Plány s startMonth přiřadí kotvené týdny k vybranému roku (Velikonoce podle gregoriánského výpočtu, Vánoce jako neděle na den nebo před 25. prosincem) a vyplní úseky mezi nimi; plány bez startMonth stále mapují týden N na startDate + (N−1)×7 dní. Týdny z externích poskytovatelů OLF nebo s neúplnou cestou se při aplikaci přeskočí. Sbory plány upravují jako jakékoli jiné a FreePlay přehraje to, co je na plánu.

Shrnutí​

PlochaMechanismus autentizaceSměrKde je implementovánoReference
REST APIBearer JWT nebo klíč cak_…PříchozíApi/src/modules/*API klíče
API klíčeToken cak_ hashovaný SHA-256Přihlašovací údajApi/.../membership/controllers/ApiKeyController.tsAPI klíče
OAuth 2.0 / Propojené aplikaceAuth code (PKCE) · device · refresh → JWT; dynamická registrace klientaPříchozíApi/.../membership/controllers/OAuthController.tsPropojené aplikace
WebhookyTajemství pro každý hook, podpis HMAC-SHA256OdchozíApi/src/shared/webhooks/ + WebhookController.tsWebhooky
MCP serverBearer JWT, OAuth JWT (objevený přes /.well-known), nebo klíč cak_…Příchozí (AI)Api/src/modules/mcp/MCP server
Poskytovatelé obsahuPodle poskytovatele: žádný / OAuth PKCE / device / formulářPříchozí obsahPackages/content-providers/Poskytovatel obsahu

Hotové konektory​

Místo toho, aby si každý budoval vše od začátku, ChurchApps dodává konektory postavené nad výše uvedenými plochami:

  • Slack a Discord — connectorType webhooku přetvoří standardní obálku na chatovou zprávu; nastavuje se celé v B1Admin, bez účtu třetí strany.
  • Mailchimp — connectorType mailchimp, který synchronizuje osoby do publika Mailchimp a mapuje členství ve skupinách a seznamech na štítky (Api/src/shared/webhooks/MailchimpConnector.ts). Na rozdíl od chatových konektorů vydává vlastní ověřené požadavky pro každou událost (upsert, archive, tag) místo POSTu na URL dodanou sborem; API klíč a ID publika jsou šifrované v webhooks.connectorConfig. Jednosměrné, pouze standardní slučovací pole.
  • Zapier a Make — spouštějí se na události webhooku a jednají přes REST API; když se Zap nebo scénář zapne, registrují si vlastní webhook (potřebují klíč s settings:write). Zdrojový kód aplikace Zapier je v repozitáři Integrations pod zapier/ (Zapier CLI, nasazováno příkazem zapier push).
  • Google Sheets — doplněk ověřený API klíčem, který na požádání exportuje Osoby, Dary, Skupiny a Účast.
  • Claude a ChatGPT — MCP klienti nasměrovaní na /mcp.

Pro vlastní kód obaluje @churchapps/integration-sdk (Packages/integration-sdk) to vše: typovaný REST klient, OAuth klient (auth-code, refresh a device flow) a ověřovač webhooků HMAC s middleware pro Express.

Související stránky​