Перейти к основному содержимому

Ключи 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)​

  1. Войдите в B1Admin под пользователем с правом Редактирование настроек.
  2. Откройте Настройки → Разработчик → Ключи API.
  3. Нажмите Новый ключ API, укажите понятное Название (например, «Zapier -- синхронизация пожертвований»), выберите хотя бы одну из Областей доступа, которые должен иметь ключ, при желании выберите дату Срок действия (оставьте пустым для ключа без срока) и нажмите Сохранить.
  4. Полный ключ 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 и подключённые приложения.

Ключ APIOAuth
Кто устанавливаетОдин администратор церквиКаждый администратор церкви авторизует приложение
Заголовок авторизацииAuthorization: Bearer cak_…Authorization: Bearer <jwt>
Срок действия токенаДо отзываДоступ ≈ 7 дней, обновление ≈ 90 дней
Лучше всего дляВнутренних скриптов, коннекторов Zapier/Make/SheetsМногоарендных сторонних приложений