SmengoAPI

Аутентификация

Каждый запрос к /api/v1 должен нести API-ключ организации в заголовке Authorization.

Формат ключа

Ключ выглядит так: smg_live_ + 43 символа (буквы, цифры, -, _) — итого 52 символа. Передаётся как Bearer-токен:

Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Пример запроса:

curl -s https://smengo.com/api/v1/org \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Как получить ключ

Владелец организации (право «Управление организацией») создаёт ключ прямо в приложении: Настройки → Интеграции → блок «API-ключи» → «Создать ключ». При создании выбираются скоупы — набор скоупов ключа не может быть шире прав самого создателя. Пошагово — в статье «API-ключи» в справке.

Ключ показывается ровно один раз — в момент создания. Smengo хранит только его хэш, поэтому восстановить показанный ключ повторно нельзя: если потеряли — попросите выпустить новый и отозвать старый.

Права ключа

Ключ read-only и не может дать больше прав, чем есть у создавшего его пользователя: набор скоупов ключа — подмножество прав его владельца в приложении. Что именно открывает каждый скоуп — в Справочнике скоупов.

Отзыв ключа

Ключ можно отозвать в любой момент — все запросы с ним сразу начнут получать 401. Отозванный, битый по формату, неизвестный или отсутствующий ключ — Smengo намеренно возвращает один и тот же ответ 401 unauthorized для всех этих случаев, не раскрывая причину. Так API не даёт постороннему проверить перебором, существует ли вообще какой-то ключ: детали ошибки не позволяют отличить «неправильный формат» от «ключ был, но его отозвали».

Ключ — серверный секрет

Как и любой секрет, API-ключ нельзя встраивать в код, который исполняется в браузере, мобильном приложении или другом месте, доступном пользователю. Храните его в переменных окружения бэкенда. CORS для /api/v1 выключен намеренно — вызовы из браузера не предполагаются архитектурой API.

Что дальше

Была ли статья полезна?