API автентифікації

Для автентифікаційних заголовків і загальних полів відповідей дивіться Загальні відомості API.

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

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

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

POST /auth/external/telegram_bot

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

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

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

Тіло запиту

Відповідь

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

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

Сесії

Усі кінцеві точки /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" для сесій з електронною поштою/паролем і "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 }

Вихід з режиму Sudo Auth required

POST /auth/sudo/exit

Завершує сесію sudo викликової сторони (адміністратор, що діє як користувач, див. POST /admin/users/:id/sudo). 400 auth.not_sudo_session для будь-якої іншої сесії.

Відповідь

{ "message": "auth.sudo_ended" }