Ключі 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)
- Увійдіть до B1Admin як користувач із дозволом Редагування налаштувань.
- Відкрийте Налаштування → Розробник → Ключі API.
- Натисніть Новий ключ API, дайте йому впізнаваєму назву (наприклад, «Zapier — синхронізація пожертв»), виберіть області доступу, які має мати ключ, і натисніть Зберегти.
- Повний ключ
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 та підключеними застосунками.
| Ключ API | OAuth | |
|---|---|---|
| Хто встановлює | Один адміністратор церкви | Кожен адміністратор церкви авторизує застосунок |
| Заголовок автентифікації | Authorization: Bearer cak_… | Authorization: Bearer <jwt> |
| Термін дії токена | До відкликання | Доступ ≈ 7 днів, оновлення ≈ 90 днів |
| Найкраще для | Внутрішні скрипти, коннектори Zapier/Make/Sheets | Багатоорендарні сторонні застосунки |