Перейти до основного вмісту

Ключі API

Ключі API (персональні токени доступу) — найпростіший спосіб автентифікації в API B1 із серверного скрипта, стороннього коннектора (Zapier, Make, Google Sheets) або в будь-якому випадку, коли повний потік OAuth є надмірним. Ключ прив'язаний до конкретної особи в конкретній церкві та успадковує її дозволи, які можна звузити за допомогою необов'язкового набору областей доступу.

Перш ніж почати

  • Ключі створює й керує ними адміністратор церкви з дозволом Редагування налаштувань
  • Необроблений ключ показується один раз під час створення — одразу збережіть його в безпечному місці
  • Усі запити до API мають використовувати HTTPS

Формат ключа​

Ключ API B1 має такий вигляд:

cak_<prefix>.<secret>
  • cak_ — фіксований ідентифікатор (префікс ключа API, за яким шар автентифікації виконує пошук)
  • <prefix> — 8-символьний публічний сегмент для пошуку
  • <secret> — 48-символьний секрет; на сервері зберігається лише його хеш SHA-256

Повний ключ передається серверу у стандартному заголовку Bearer:

Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7

Шар автентифікації API спрямовує будь-який токен, що починається з cak_, до шляху для ключів API, хешує секрет, знаходить ключ за префіксом і визначає поточні дозволи особи, якій належить ключ. Тому скасування дозволу в B1Admin набуває чинності з наступного запиту, і ключ ніколи не розходиться з роллю.

Створення ключа (B1Admin)​

  1. Увійдіть до B1Admin як користувач із дозволом Редагування налаштувань.
  2. Відкрийте Налаштування → Розробник → Ключі API.
  3. Натисніть Новий ключ API, дайте йому впізнаваєму назву (наприклад, «Zapier — синхронізація пожертв»), виберіть області доступу, які має мати ключ, і натисніть Зберегти.
  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Переглядати / редагувати налаштування церкви (потрібно для програмної реєстрації вебхуків)
workflows:read / workflows:writeПереглядати робочі процеси та завдання / запускати й редагувати робочі процеси. Запуск робочого процесу може надсилати електронні листи й текстові повідомлення, викликати вебхуки та змінювати членство в групах
offline_accessДозволяє довгострокові токени оновлення (лише для потоків OAuth — на ключі API не впливає)

Області write неявно включають відповідну область read. Дозволи адміністратора сервера та домену навмисно не надаються як області доступу — облікові дані з обмеженими областями ніколи не можуть отримати права адміністрування сайту.

поради

Якщо ви використовуватимете ключ для реєстрації вебхуків (наприклад, для інтеграції 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) від адміністратора церкви з дозволом Редагування налаштувань.

Метод і шляхПризначення
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 та підключеними застосунками.

Ключ APIOAuth
Хто встановлюєОдин адміністратор церквиКожен адміністратор церкви авторизує застосунок
Заголовок автентифікаціїAuthorization: Bearer cak_…Authorization: Bearer <jwt>
Термін дії токенаДо відкликанняДоступ ≈ 7 днів, оновлення ≈ 90 днів
Найкраще дляВнутрішні скрипти, коннектори Zapier/Make/SheetsБагатоорендарні сторонні застосунки