Authentication API

Про заголовки аутентифікації та загальні поля у відповідях дивіться API General.

Рекомендований спосіб аутентифікації з API - це API ключ. Дивіться API Keys, щоб дізнатися, як його згенерувати.

Зовнішня аутентифікація — Telegram Bot

Аутентифікація через Telegram Bot 30 req / 60s

POST /auth/external/telegram_bot

Аутентифікація або реєстрація за допомогою ініціалізаційних даних Telegram Mini App. Сервер перевіряє HMAC-SHA-256 хеш з токеном бота перед видачею токена.

Надішліть сирий рядок window.Telegram.WebApp.initData із вашого Mini App — не initDataUnsafe (розпарсений об'єкт). Надсилання розпарсеного об'єкта ненадійне, оскільки точна JSON-кодування, що використовується Telegram для обчислення хеша, не може бути відновлена.

Повертає ту ж саму структуру { accessToken, user }, що й інші точки аутентифікації.

Тіло запиту

Відповідь

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "k5Xz9qR2Wp",
    "name": "Ivan Drago",
    "avatarUrl": "https://api.telegram.org/file/bot.../photo.jpg"
  }
}

Сесії, створені цією точкою, мають type: "telegram" — видно в List Sessions.

Сесії

Всі endpoint /auth/sessions вимагають автентифікації.

Перелік сесій Auth required

GET /auth/sessions

Перелік активних сесій для поточного користувача.

Відповідь

{
  "sessions": [
    {
      "id": "k5Xz9qR2Wp",
      "ip": "91.123.45.67",
      "type": "telegram",
      "location": { "country": "UA", "city": "Kyiv" },
      "device": {
        "browser": "Chrome 120",
        "os": "macOS 14.2",
        "device": "Desktop",
        "summary": "Chrome 120 / macOS 14.2"
      },
      "isCurrent": true,
      "lastActiveAt": "2026-03-15T12:00:00.000Z",
      "createdAt": "2026-03-10T08:00:00.000Z"
    },
    ...
  ]
}

type це "default" для сесій з email/паролями та "telegram" для аутентифікації через бот Telegram.

Відкликати сесію Auth required

DELETE /auth/sessions/:id

Відкликати конкретну сесію. Якщо відкликана сесія є поточною сесією того, хто запитує, повертається logout: true — фронтенд повинен очистити токен та перенаправити на сторінку входу.

Відповідь

{ "message": "auth.session_revoked", "logout": false }

logout: true, коли виконувач відкликав власну активну сесію.

Відкликати всі сесії Auth required

DELETE /auth/sessions

Відкликати всі сесії, крім поточної.

Відповідь

{ "message": "auth.sessions_revoked", "revokedCount": 3 }