API кључеви
API кључеви (лични приступни токени) су најједноставнији начин за аутентификацију према B1 API-ју из серверске скрипте, конектора треће стране (Zapier, Make, Google Sheets) или било где где је пун OAuth ток превише комплексан. Кључ је везан за одређену особу у одређеној цркви и наслеђује дозволе те особе, сужене опционалним скупом опсега.
Пре почетка
- Администратор цркве са дозволом Edit Settings креира и управља кључевима
- Пуни кључ се приказује само једном при креирању — одмах га сачувајте на безбедном месту
- Сви API захтеви морају користити HTTPS
Формат кључа
B1 API кључ изгледа овако:
cak_<prefix>.<secret>
cak_— фиксни идентификатор (префикс API кључа по којем слој за аутентификацију препознаје кључ)<prefix>— јавни сегмент за претрагу дужине 8 знакова<secret>— тајни део дужине 48 знакова; на серверу се чува само SHA-256 хеш
Цео кључ се серверу прослеђује у стандардном Bearer заглављу:
Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7
Слој за аутентификацију API-ја сваки токен који почиње са cak_ усмерава на путању за API кључеве, хешира тајни део, претражује кључ по префиксу и утврђује актуелне дозволе особе којој кључ припада. Зато опозивање дозволе у B1Admin ступа на снагу већ при следећем захтеву, а кључ никада не одступа од улоге.
Креирање кључа (B1Admin)
- Пријавите се на B1Admin као корисник са дозволом Edit Settings.
- Отворите Settings → Developer → API Keys.
- Кликните на New API Key, дајте му препознатљив назив (нпр. „Zapier — donations sync“), изаберите опсеге које кључ треба да има и кликните на Save.
- Цео кључ
cak_…се приказује једном у дијалогу. Копирајте га у конфигурацију своје интеграције пре затварања — касније га није могуће поново добити. Увек можете креирати нови кључ.
Опсези
Опсег сужава оно што кључ може даради — никада не може да додели дозволу коју основна особа нема. Ако нема опсега (празно), кључ има пун скуп дозвола те особе.
| Опсег | Омогућава |
|---|---|
people:read / people:write | Преглед / измена особа, домаћинстава, чланова група |
groups:read / groups:write | Преглед / измена група и њиховог чланства |
donations:read / donations:write | Преглед / бележење донација |
attendance:read / attendance:write | Преглед / бележење присуства, сесија и пријава |
forms:write | Управљање обрасцима (право читања подразумева се уз право писања) |
content:read / content:write | Преглед / измена садржаја сајта, пријава и стриминга |
messaging:read / messaging:write | Читање порука; писање такође омогућава слање SMS-ова |
roles:read / roles:write | Преглед / измена дефиниција улога |
settings:read / settings:write | Преглед / измена подешавања цркве (потребно за програмску регистрацију webhook-ова) |
workflows:read / workflows:write | Преглед токова рада и задатака / покретање и измена токова рада. Покретање тока рада може слати имејлове и поруке, активирати webhook-ове и мењати чланство у групама |
offline_access | Дозвољава дугорочне refresh токене (само OAuth токови — нема дејства на API кључеве) |
Опсези за write подразумевано укључују одговарајући read. Серверске и администраторске дозволе домена намерно нису изложене као опсези — акредитив са опсегом никада не може да се издигне до администрације сајта.
Ако ћете кључ користити за регистрацију webhook-ова (нпр. за Zapier или Make интеграцију), кључу је потребан settings:write. Кључ само са people:read без упозорења добија грешку 403 на POST /membership/webhooks.
Коришћење кључа
Као и сваки Bearer токен — сваки крајњи чвор са аутентификацијом прихвата API кључеве исто као и JWT-ове:
curl https://api.churchapps.org/membership/people \
-H "Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7"
Захтев чији кључ нема довољно опсега добија одговор 403 Forbidden у истом облику као и било која грешка због недостатка дозволе.
Управљање кључевима преко API-ја
Сви крајњи чворови се налазе у оквиру путање /membership/apiKeys модула Membership и захтевају JWT (а не API кључ) од администратора цркве са дозволом Edit Settings.
| Метода и путања | Сврха |
|---|---|
GET /membership/apiKeys | Списак кључева цркве (без тајне — само id, name, prefix, scopes, lastUsedAt, expiresAt, createdAt) |
GET /membership/apiKeys/scopes | Списак свих доступних назива опсега — за интерфејс за креирање кључа |
POST /membership/apiKeys | Креирање новог кључа. Тело: { "name": "...", "scopes": ["people:read"] }. Одговор садржи пуни cak_… кључ једном. |
DELETE /membership/apiKeys/:id | Опозив кључа — ступа на снагу при следећем захтеву |
Опозван кључ престаје да важи одмах — нема периода милости.
Препоруке за добру праксу
- Један кључ по интеграцији. Ако је нешто компромитовано, опозивате само један кључ, а остали остају функционални.
- Додељујте најуже опсеге који су довољни. Извоз у Google Sheets треба само
people:read, а неsettings:write. - Везујте кључ за сервисни налог, а не за стварног запосленог. Ако запослени напусти организацију, и његов приступ B1-у престаје — као и сви кључеви креирани под његовим налогом.
- Чувајте кључеве у менаџеру тајни (променљиве окружења вашег хостинг провајдера, AWS Secrets Manager и слично) — никада у систему за контролу верзија.
- Замењујте кључеве ако сумњате на изложеност: креирајте нови кључ, ажурирајте интеграцију, па обришите стари.
Чиме се разликује од OAuth-а
API кључеви су погодни када ваша црква је једина која користи интеграцију. За конектор који треба да приступа многим црквама уз изричиту сагласност сваке од њих — попут SaaS апликације дељене у B1 заједници — уместо тога користите OAuth и повезане апликације.
| API кључ | OAuth | |
|---|---|---|
| Ко га инсталира | Један администратор цркве | Сваки администратор цркве одобрава апликацију |
| Заглавље за аутентификацију | Authorization: Bearer cak_… | Authorization: Bearer <jwt> |
| Трајање токена | До опозива | Приступ ≈ 7 дана, refresh ≈ 90 дана |
| Најпогодније за | Интерне скрипте, Zapier/Make/Sheets конекторе | Вишекорисничке апликације трећих страна |