Authentication API

For authentication headers and common response fields, see API General.

The recommended way to authenticate with the API is via an API key. See API Keys for how to generate one.

External Auth — Telegram Bot

Authenticate via Telegram Bot 30 req / 60s

POST /auth/external/telegram_bot

Authenticate or register using Telegram Mini App initData. The server verifies the HMAC-SHA-256 hash against the bot token before issuing a token.

Send the raw window.Telegram.WebApp.initData string from your Mini App — not initDataUnsafe (the parsed object). Sending a parsed object is unreliable because the exact JSON encoding used by Telegram to compute the hash cannot be reconstructed.

Returns the same { accessToken, user } shape as all other auth endpoints.

Request Body

Response

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

Sessions created by this endpoint have type: "telegram" — visible in List Sessions.

Sessions

All /auth/sessions endpoints require authentication.

List Sessions Auth required

GET /auth/sessions

List active sessions for the current user.

Response

{
  "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 is "default" for email/password sessions and "telegram" for Telegram bot auth.

Revoke Session Auth required

DELETE /auth/sessions/:id

Revoke a specific session. If the revoked session is the caller's current session, logout: true is returned — the frontend should clear the token and redirect to login.

Response

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

logout: true when the caller revoked their own active session.

Revoke All Sessions Auth required

DELETE /auth/sessions

Revoke all sessions except the current one.

Response

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