Пријавите се на главни садржај

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)​

  1. Пријавите се на B1Admin као корисник са дозволом Edit Settings.
  2. Отворите Settings → Developer → API Keys.
  3. Кликните на New API Key, дајте му препознатљив назив (нпр. „Zapier — donations sync“), изаберите опсеге које кључ треба да има и кликните на Save.
  4. Цео кључ 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 конектореВишекорисничке апликације трећих страна