Ugrás a fő tartalomra

API-kulcsok

Az API-kulcsok (személyes hozzáférési tokenek) a legegyszerűbb módja a B1 API-hoz való hitelesítésnek szerveroldali szkriptekből, harmadik féltől származó összekötőkből (Zapier, Make, Google Sheets), illetve olyan helyzetekben, ahol a teljes OAuth-folyamat túlzás volna. A kulcs egy adott személyhez kötődik egy adott gyülekezetben, és örökli annak a személynek a jogosultságait, amelyeket opcionálisan hatókörök (scopes) szűkíthetnek.

Mielőtt elkezdi

  • A kulcsokat egy olyan gyülekezeti adminisztrátor hozza létre és kezeli, akinek van Beállítások szerkesztése jogosultsága
  • A nyers kulcs létrehozáskor egyszer jelenik meg — azonnal tárolja biztonságos helyen
  • Minden API-kérésnek HTTPS-t kell használnia

A kulcs formátuma​

Egy B1 API-kulcs így néz ki:

cak_<prefix>.<secret>
  • cak_ — rögzített azonosító (az API-kulcs előtag, amelyre a hitelesítési réteg illeszkedik)
  • <prefix> — 8 karakteres nyilvános keresési szegmens
  • <secret> — 48 karakteres titkos kód; a szerveroldalon csak annak SHA-256 hash-e tárolódik

A teljes kulcs a szabványos bearer fejlécben kerül át a szervernek:

Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7

Az API hitelesítési rétege minden cak_-kal kezdődő tokent az API-kulcs útvonalra irányít, hash-eli a titkos részt, előtag alapján keresi meg a kulcsot, majd feloldja a kulcs személyének aktuális jogosultságait. Ennek köszönhetően a B1Admin-ban visszavont jogosultság a következő kéréstől érvénybe lép, és a kulcs soha nem válik el a szerepkörtől.

Kulcs létrehozása (B1Admin)​

  1. Jelentkezzen be a B1Admin-ba olyan felhasználóként, akinek van Beállítások szerkesztése jogosultsága.
  2. Nyissa meg a Beállítások → Fejlesztő → API-kulcsok menüpontot.
  3. Kattintson az Új API-kulcs gombra, adjon neki felismerhető nevet (pl. „Zapier — adományszinkronizálás”), jelölje ki a kulcsnak szánt hatóköröket, majd kattintson a Mentés gombra.
  4. A teljes cak_… kulcs egyszer jelenik meg egy párbeszédpanelen. A bezárás előtt másolja be az integrációja konfigurációjába, mert később nincs mód visszakérni. Mindig létrehozhat új kulcsot.

Hatókörök​

A hatókör szűkíti, hogy mit tehet a kulcs. Soha nem adhat olyan jogosultságot, amellyel az alapul szolgáló személy nem rendelkezik. Ha nincs megadva hatókör, a kulcs a személy teljes jogosultságkészletével rendelkezik.

HatókörEngedélyezi
people:read / people:writeSzemélyek, háztartások és csoporttagok megtekintése / szerkesztése
groups:read / groups:writeCsoportok és tagságuk megtekintése / szerkesztése
donations:read / donations:writeAdományok megtekintése / rögzítése
attendance:read / attendance:writeRészvétel, alkalmak és bejelentkezések megtekintése / rögzítése
forms:writeŰrlapok kezelése (az olvasási jog az írásból következik)
content:read / content:writeWeboldal-tartalom, regisztrációk és streaming megtekintése / szerkesztése
messaging:read / messaging:writeÜzenetek olvasása; az írási jog SMS küldését is engedélyezi
roles:read / roles:writeSzerepkör-definíciók megtekintése / szerkesztése
settings:read / settings:writeGyülekezeti beállítások megtekintése / szerkesztése (kötelező a webhookok programozott regisztrálásához)
workflows:read / workflows:writeMunkafolyamatok és feladatok megtekintése / munkafolyamatok futtatása és szerkesztése. Egy munkafolyamat futtatása e-mailt és SMS-t küldhet, webhookokat indíthat, és módosíthatja a csoporttagságot
offline_accessHosszú életű frissítő tokenek engedélyezése (csak OAuth-folyamatokban; API-kulcsoknál nincs hatása)

Az írási (write) hatókörök magukba foglalják a megfelelő olvasási (read) hatókört. A szerver- és domain-adminisztrátori jogosultságok szándékosan nincsenek hatókörként megjelenítve: egy hatókörrel szűkített hitelesítő adat soha nem emelkedhet webhely-adminisztrátori szintre.

tipp

Ha a kulcsot webhookok regisztrálására fogja használni (pl. Zapier vagy Make integrációhoz), a kulcsnak settings:write hatókör kell. Egy csak people:read hatókörű kulcs csendben 403-as hibát kap a POST /membership/webhooks végponton.

Kulcs használata​

Ugyanúgy használható, mint bármely bearer token: minden hitelesített végpont pontosan úgy fogadja az API-kulcsokat, ahogy a JWT-ket:

curl https://api.churchapps.org/membership/people \
-H "Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7"

Ha egy kérés kulcsának nincs elegendő hatóköre, a válasz 403 Forbidden lesz, ugyanabban a formában, mint bármely jogosultság-megtagadási hiba.

Kulcsok kezelése az API-n keresztül​

Minden végpont a Membership modul /membership/apiKeys útvonala alatt érhető el. Ezek JWT-t igényelnek (nem API-kulcsot), és csak olyan gyülekezeti adminisztrátortól fogadják el, akinek van Beállítások szerkesztése jogosultsága.

Metódus és útvonalCélja
GET /membership/apiKeysA gyülekezet kulcsainak listázása (titkos kód nélkül, csak id, name, prefix, scopes, lastUsedAt, expiresAt, createdAt)
GET /membership/apiKeys/scopesAz összes elérhető hatókörnév listája, kulcslétrehozó felülethez
POST /membership/apiKeysÚj kulcs létrehozása. Törzs: { "name": "...", "scopes": ["people:read"] }. A válasz egyszer tartalmazza a nyers cak_… kulcsot.
DELETE /membership/apiKeys/:idKulcs visszavonása; a következő kéréstől érvényesül

A visszavont kulcs azonnal érvényét veszíti, nincs türelmi idő.

Ajánlott gyakorlatok​

  • Integrációnként egy kulcs. Ha valami kompromittálódik, egyetlen kulcsot vonhat vissza anélkül, hogy a többit megzavarná.
  • A működő legszűkebb hatóköröket adja meg. Egy Google Sheets-exporthoz csak people:read kell, nem settings:write.
  • Szolgáltatásfiókhoz kösse a kulcsot, ne valódi munkatárshoz. Ha egy munkatárs távozik, B1-hozzáférése megszűnik, és vele együtt az ő személyazonossága alatt létrehozott kulcsok is.
  • Tárolja a kulcsokat titkos kezelőben (tárhelyszolgáltatója környezeti változói, AWS Secrets Manager stb.), soha ne verziókezelőben.
  • Cserélje a kulcsokat, ha kiszivárgásra gyanakszik: hozzon létre új kulcsot, frissítse vele az integrációt, majd törölje a régit.

Az OAuth-tól való különbség​

Az API-kulcsok akkor megfelelőek, ha az Ön gyülekezete az egyetlen, amely használja az integrációt. Olyan összekötőhöz, amely több gyülekezet eléréséhez kér kifejezett, gyülekezetenkénti hozzájárulást, például a B1-közösségben megosztott SaaS-alkalmazáshoz, inkább a OAuth és csatlakoztatott alkalmazások oldalt használja.

API-kulcsOAuth
Ki telepítiEgy gyülekezeti adminisztrátorMinden gyülekezeti adminisztrátor engedélyezi az alkalmazást
Hitelesítési fejlécAuthorization: Bearer cak_…Authorization: Bearer <jwt>
Token élettartamaVisszavonásigHozzáférés ≈ 7 nap, frissítés ≈ 90 nap
Ideális a következőkhözBelső szkriptek, Zapier/Make/Sheets összekötőkTöbbbérlős harmadik féltől származó alkalmazások