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.

Що далі

Чи була стаття корисною?