Ключи API
Ключи API (персональные токены доступа) -- самый простой способ аутентификации в B1 API из серверного скрипта, стороннего коннектора (Zapier, Make, Google Sheets) или в любом месте, где полный поток OAuth избыточен. Ключ привязан к конкретному человеку в конкретной церкви и наследует его права, которые можно сузить с помощью необязательного набора областей действия (scopes).
Прежде чем начать
- Ключи создаёт и управляет ими администратор церкви с правом Редактирование настроек
- Сам ключ показывается один раз при создании -- сразу сохраните его в надёжном месте
- Все запросы к 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 под пользователем с правом Редактирование настроек.
- Откройте Настройки → Разработчик → Ключи API.
- Нажмите Новый ключ API, укажите понятное Название (например, «Zapier -- синхронизация пожертвований»), выберите хотя бы одну из Областей доступа, которые должен иметь ключ, при желании выберите дату Срок действия (оставьте пустым для ключа без срока) и нажмите Сохранить.
- Полный ключ
cak_…показывается один раз в диалоге. Скопируйте его в конфигурацию интеграции до закрытия окна -- получить его позже будет нельзя. Вы всегда можете создать новый ключ.
Области доступа (Scopes)
Область доступа сужает то, что может делать ключ, -- она никогда не может дать право, которого нет у лежащего в основе человека. Пустой набор областей означает, что ключ получает полный набор прав человека; B1Admin всегда требует хотя бы одну область, поэтому ключ без областей можно создать только через API.
| Область | Разрешает |
|---|---|
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 | Просмотр рабочих процессов и задач / запуск и редактирование рабочих процессов. Запуск рабочего процесса может отправлять email и SMS, вызывать вебхуки и менять состав групп |
offline_access | Разрешает долгоживущие refresh-токены (только для потоков 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 | Многоарендных сторонних приложений |