Аутентификация
Публичный API BigBen CRM принимает запросы только с валидным API-ключом школы. На этой странице — где взять ключ, как передавать его в запросах и что делать при компрометации.
Где получить ключ
Ключ выпускается в личном кабинете школы: раздел Настройки → Интеграции → API-ключи (управление ключами в интерфейсе платформы, отдельно от самого публичного API). Выпускать и отзывать ключи может пользователь с ролью Владелец или Admin — остальным ролям раздел недоступен.
Тариф
Продукт планирует открыть выдачу ключей с тарифа «Расширенный». На момент публикации этой страницы ограничение ещё не действует на уровне API — уточняйте актуальные условия у своей школы.
При выпуске укажите название ключа и выберите один или оба скоупа (read, write). Платформа показывает готовый ключ один раз, сразу после создания — сохраните его сразу: повторно посмотреть plaintext нельзя, в базе хранится только sha256-хеш.
Формат ключа
bb_<prefix>_<secret>prefix — восемь hex-символов, по нему ключ узнают в списке (сам secret повторно не показывается). Пример вида ключа (не рабочий): bb_a1b2c3d4_M8x1F0qWn9….
Как передавать ключ
Ключ передаётся заголовком Authorization с типом Bearer:
curl https://platformapi.bigbencrm.ru/api/public/v1/students \
-H "Authorization: Bearer bb_a1b2c3d4_M8x1F0qWn9..."Успешный ответ:
{
"data": [
{
"id": 4821,
"fio": "Иванова Мария",
"phone": "+79261234567",
"email": "maria@example.com",
"balance_kopecks": 150000,
"active_groups": null
}
],
"meta": { "page": 1, "per_page": 20, "total": 187 }
}Если заголовка нет, ключ не распознан, отозван или истёк — платформа отвечает 401 с кодом unauthorized. Полный разбор кодов ошибок — на странице «Коды ошибок».
Скоупы
У ключа ровно два возможных скоупа:
| Скоуп | Что даёт |
|---|---|
read | GET-методы: справочники, группы, расписание, ученики, платежи |
write | POST-методы записи (лиды, запись на пробный урок, зачисление в группу) и все read-методы — обратное не действует |
Если скоупа не хватает, платформа отвечает 403 с кодом insufficient_scope. Выдайте ключу нужный скоуп при создании либо используйте ключ с другим набором скоупов.
Если ключ скомпрометирован
Отдельной операции «перевыпустить ключ» нет. Порядок действий:
- Выпустите новый ключ в том же разделе интеграций.
- Обновите его в своей интеграции и убедитесь, что запросы проходят.
- Отзовите скомпрометированный ключ — кнопкой «Отозвать» в том же разделе (действие делает Владелец или Admin под своей сессией в интерфейсе, самим API-ключом это не сделать). После отзыва в базе проставляется
revoked_at, и ключ сразу перестаёт приниматься публичным API.
Не отзывайте старый ключ раньше, чем переключите интеграцию на новый — иначе запросы прервутся раньше времени.
Дальше
- Коды ошибок — полный список кодов и что с ними делать.
- Лимиты запросов — сколько запросов можно делать одним ключом.