API ключи
API ключи (личные токены доступа) — это самый простой способ аутентификации на B1 API из скрипта на стороне сервера, соединителя третьей стороны (Zapier, Make, Google Sheets) или везде, где полный OAuth поток избыточен. Ключ привязан к конкретному человеку в конкретной церкви и наследует разрешения этого человека, сужено необязательным набором областей.
Перед началом
- Администратор церкви с разрешением Редактировать параметры создает и управляет ключами
- Исходный ключ показывается один раз при создании — сохраните его где-то в безопасности немедленно
- Все 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_…показывается один раз в диалоговом окне. Скопируйте его в конфигурацию интеграции перед закрытием — нет способа получить его позже. Вы всегда можете создать новый ключ.
Области
Область сужает то, что может сделать ключ — она никогда не может предоставить разрешение, которое базовый человек не имеет. Пустые / нет областей означает, что ключ имеет полный набор разрешений человека.
| Область | Позволяет |
|---|---|
people:read / people:write | Просмотр / редактирование людей, домохозяйств, членов группы |
groups:read / groups:write | Просмотр / редактирование групп и их членства |
donations:read / donations:write | Просмотр / запись пожертвований |
attendance:read / attendance:write | Просмотр / запись посещаемости, сессий, регистраций |
forms:write | Управление формами (доступ на чтение неявен в write) |
content:read / content:write | Просмотр / редактирование контента сайта, регистраций, потоковой трансляции |
messaging:read / messaging:write | Чтение сообщений; write также позволяет отправлять SMS |
roles:read / roles:write | Просмотр / редактирование определений ролей |
settings:read / settings:write | Просмотр / редактирование параметров церкви (требуется для программной регистрации webhooks) |
offline_access | Разрешить долгоживущие токены обновления (только потоки OAuth — не влияет на API ключи) |
write области неявно включают соответствующее read. Разрешения администратора сервера и домена намеренно не предоставляются как области — учетные данные с областью никогда не могут повыситься до администрирования сайта.
Если вы будете использовать ключ для регистрации webhooks (например, для интеграции Zapier или Make), ключ нуждается в settings:write. Ключ с people:read только молча 403s на POST /membership/webhooks.
Использование ключа
То же самое, что любой bearer токен — каждая аутентифицированная конечная точка принимает API ключи точно так же, как она принимает JWTs:
curl https://api.churchapps.org/membership/people \
-H "Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7"
Запрос, чей ключ имеет недостаточные области, отвечает 403 Forbidden с той же формой, которую использует любая ошибка отказа в доступе.
Управление ключами через API
Все конечные точки находятся под путем модуля Membership /membership/apiKeys и требуют 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 | Многопользовательские приложения третьих сторон |