Prejsť na hlavný obsah

API kľúče

API kľúče (osobné prístupové tokeny) sú najjednoduchší spôsob, ako sa autentifikovať voči B1 API zo serverového skriptu, konektora tretej strany (Zapier, Make, Google Sheets) alebo kdekoľvek, kde je úplný tok OAuth zbytočne zložitý. Kľúč je viazaný na konkrétnu osobu v konkrétnej cirkvi a dedí oprávnenia tejto osoby, ktoré je možné voliteľne zúžiť sadou rozsahov (scopes).

Predtým, ako začnete

  • Kľúče vytvára a spravuje správca cirkvi s oprávnením Upraviť nastavenia
  • Surový kľúč sa zobrazí iba raz pri vytvorení – okamžite ho uložte na bezpečné miesto
  • Všetky požiadavky na API musia používať HTTPS

Formát kľúča​

Kľúč B1 API vyzerá takto:

cak_<prefix>.<secret>
  • cak_ — pevný identifikátor (prefix API kľúča, podľa ktorého autentifikačná vrstva kľúč rozpoznáva)
  • <prefix> — 8-znakový verejný vyhľadávací segment
  • <secret> — 48-znakové tajomstvo; na strane servera sa ukladá iba hash SHA-256

Úplný kľúč sa serveru predkladá v štandardnej hlavičke bearer:

Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7

Autentifikačná vrstva API smeruje každý token začínajúci na cak_ do cesty pre API kľúče, zahashuje tajomstvo, vyhľadá kľúč podľa prefixu a zistí aktuálne oprávnenia osoby, ktorej kľúč patrí. Odobratie oprávnenia v B1Admin sa preto prejaví už pri ďalšej požiadavke a kľúč nikdy nie je nesúladný s rolou.

Vytvorenie kľúča (B1Admin)​

  1. Prihláste sa do B1Admin ako používateľ s oprávnením Upraviť nastavenia.
  2. Otvorte Nastavenia → Vývojár → API kľúče.
  3. Kliknite na Nový API kľúč, zadajte rozpoznateľný názov (napr. „Zapier — synchronizácia darov“), vyberte rozsahy, ktoré má kľúč mať, a kliknite na Uložiť.
  4. Úplný kľúč cak_… sa zobrazí iba raz v dialógovom okne. Skopírujte ho do konfigurácie svojej integrácie ešte pred zatvorením okna – neskôr ho už nebude možné získať. Nový kľúč môžete kedykoľvek vytvoriť znova.

Rozsahy (scopes)​

Rozsah kľúč zužuje – nikdy nemôže udeliť oprávnenie, ktoré osoba nemá. Prázdny zoznam rozsahov znamená, že kľúč má celú sadu oprávnení danej osoby.

RozsahUmožňuje
people:read / people:writeZobrazovanie / úprava osôb, domácností, členov skupín
groups:read / groups:writeZobrazovanie / úprava skupín a ich členstva
donations:read / donations:writeZobrazovanie / zaznamenávanie darov
attendance:read / attendance:writeZobrazovanie / zaznamenávanie účasti, relácií a prihlásení
forms:writeSpráva formulárov (prístup na čítanie je implicitne súčasťou zápisu)
content:read / content:writeZobrazovanie / úprava obsahu webu, registrácií a streamovania
messaging:read / messaging:writeČítanie správ; zápis umožňuje aj odosielanie SMS
roles:read / roles:writeZobrazovanie / úprava definícií rolí
settings:read / settings:writeZobrazovanie / úprava nastavení cirkvi (potrebné na programovú registráciu webhookov)
workflows:read / workflows:writeZobrazovanie pracovných postupov a úloh / spúšťanie a úprava pracovných postupov. Spustenie pracovného postupu môže odoslať e-maily a správy, spustiť webhooky a zmeniť členstvo v skupinách
offline_accessUmožňuje dlhodobo platné obnovovacie tokeny (iba pri tokoch OAuth – na API kľúče nemá žiadny vplyv)

Rozsahy write implicitne zahŕňajú zodpovedajúci read. Oprávnenia serverového a doménového administrátora nie sú úmyselne sprístupnené ako rozsahy – poverenie s obmedzeným rozsahom nikdy nemôže získať správcovský prístup k webu.

tip

Ak budete kľúč používať na registráciu webhookov (napr. pre integráciu so Zapier alebo Make), kľúč potrebuje settings:write. Kľúč iba s people:read bez upozornenia vráti chybu 403 pri POST /membership/webhooks.

Používanie kľúča​

Rovnako ako ľubovoľný bearer token – každý autentifikovaný koncový bod prijíma API kľúče presne tak, ako prijíma tokeny JWT:

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

Ak má kľúč v požiadavke nedostatočné rozsahy, server odpovie 403 Forbidden v rovnakom tvare, ako každá iná chyba odmietnutia oprávnenia.

Správa kľúčov cez API​

Všetky koncové body sa nachádzajú pod cestou /membership/apiKeys modulu Membership a vyžadujú JWT (nie API kľúč) od správcu cirkvi s oprávnením Upraviť nastavenia.

Metóda a cestaÚčel
GET /membership/apiKeysVýpis kľúčov cirkvi (bez tajomstva – iba id, name, prefix, scopes, lastUsedAt, expiresAt, createdAt)
GET /membership/apiKeys/scopesZoznam všetkých dostupných názvov rozsahov – pre používateľské rozhranie na vytváranie kľúčov
POST /membership/apiKeysVytvorenie nového kľúča. Telo: { "name": "...", "scopes": ["people:read"] }. Odpoveď obsahuje surový kľúč cak_… iba raz.
DELETE /membership/apiKeys/:idOdvolanie kľúča – prejaví sa pri ďalšej požiadavke

Odvolaný kľúč prestane fungovať okamžite – neexistuje žiadna lehota na prechod.

Osvedčené postupy​

  • Jeden kľúč pre každú integráciu. Ak dôjde ku kompromitácii, odvoláte iba jeden kľúč bez narušenia ostatných.
  • Vytvárajte čo najužšie rozsahy, ktoré stačia. Export do Google Sheets potrebuje iba people:read, nie settings:write.
  • Viažte kľúč na servisný účet, nie na skutočného zamestnanca. Keď zamestnanec odíde, jeho prístup k B1 sa skončí – a spolu s ním aj všetky kľúče vytvorené pod jeho identitou.
  • Ukladajte kľúče do správcu tajomstiev (premenné prostredia vášho hostingového poskytovateľa, AWS Secrets Manager a pod.) – nikdy nie do systému správy verzií.
  • Ak máte podozrenie na únik, kľúče obnovte: vytvorte nový kľúč, aktualizujte integráciu a potom starý kľúč odstráňte.

Rozdiel oproti OAuth​

API kľúče sú vhodné vtedy, keď vaša cirkev je jediná, ktorá integráciu používa. Pre konektor, ktorý potrebuje prístup k mnohým cirkvám s výslovným súhlasom každej z nich – napríklad aplikáciu SaaS zdieľanú v komunite B1 – použite namiesto toho OAuth a prepojené aplikácie.

API kľúčOAuth
Kto ho inštalujeJeden správca cirkviKaždý správca cirkvi aplikáciu autorizuje
Hlavička autentifikácieAuthorization: Bearer cak_…Authorization: Bearer <jwt>
Životnosť tokenuAž do odvolaniaPrístup ≈ 7 dní, obnovenie ≈ 90 dní
Najvhodnejšie preInterné skripty, konektory Zapier/Make/SheetsViacnájomové aplikácie tretích strán