🔐 Access API — контроль доступа

Централизованная авторизация сотрудников. Сервис спрашивает нас, можно ли пускать пользователя; при увольнении мы сами отзываем доступ через webhook. Источник правды — статус сотрудника (работает/уволен). Идентификация по Telegram-аккаунту.

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

Каждый запрос к API — с вашим ключом в заголовке. Ключ выдаётся в Telegram-боте (меню «🔌 API-доступы»). Ключ секретный, показывается один раз.

Authorization: Bearer <ВАШ_КЛЮЧ>

POST /v1/access/check

Вызывайте при входе пользователя и на каждой новой сессии. Возвращает решение.

Запрос:

{
  "tg_id": 5496126295,
  "tg_username": "nicksmi"
}

Достаточно любого из полей, но передавайте оба, если есть: tg_username используется для решения, tg_id — чтобы мы могли адресно отозвать доступ и заметить смену ника.

Ответ:

{
  "allow": true,
  "status": "active",      // active | fired | unknown | conflict
  "reason": "Сотрудник работает",
  "username": "nicksmi"
}

Пример (curl):

curl -X POST https://access-api.smi1.net/v1/access/check \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tg_id": 5496126295, "tg_username": "nicksmi"}'

GET /v1/access/active

Полный список username работающих — для периодической сверки на вашей стороне (страховка).

curl https://access-api.smi1.net/v1/access/active -H "Authorization: Bearer $KEY"

Webhook отзыва (мы → вы)

Когда сотрудника увольняют, мы сами шлём POST на ваш webhook-URL (укажите его в карточке сервиса в боте). Тело подписано HMAC-SHA256 на вашем webhook_secret — проверяйте подпись, чтобы доверять запросу.

Что прилетит:

POST <ваш webhook_url>
X-Event: revoke
X-Signature: <hex HMAC-SHA256 тела>

{"event":"revoke","username":"ivanov","tg_ids":[12345678],"ts":1720000000}

Ваша задача по этому запросу — закрыть доступ / убить сессии пользователя.

Проверка подписи (Python):

import hmac, hashlib
def verify(secret: str, raw_body: bytes, signature: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Как правильно интегрироваться

Не кэшируйте «allow» навсегда — перепроверяйте на каждой новой сессии. Так потерянный webhook не оставит уволенного с доступом.

Интерактивная схема API: https://access-api.smi1.net/docs