This guide explains how to let players sign in from a Telegram Mini App using the telegram-auth plugin, displayed in the admin panel as Telegram Mini App Auth.
The plugin verifies the initData that Telegram gives the Mini App, then either signs in the linked player or creates a new account.
Enabling the Plugin
The plugin source ships in the plugins/telegram-auth directory of the codebase, but it is not part of the Docker image and is not active by default. You install it like any other plugin.
- Build the archive from
plugins/telegram-authwithnpm install, thennpm run pack. This produces a.tgzfile. - In the admin sidebar, go to Plugins and click Upload Plugin, then choose the file.
- Click Activate on Telegram Mini App Auth.
- Click the Settings (gear) button and enter the Bot Token.
- In Telegram, point your bot’s Mini App at
https://<your-host>/plugins/telegram-auth/public/mini-app.
Required permission: Super-admin for upload, activate, and saving settings. See Plugin Management.
While the plugin is active, GET /api/v1/auth/providers includes telegram. The Continue with Telegram button on the login page appears only when that is the case and the page is open inside Telegram.
Settings
| Setting | Key | Default | Description |
|---|---|---|---|
| Bot Token | botToken | None | Used to verify initData. Encrypted at rest. |
| InitData Max Age (seconds) | maxInitDataAgeSeconds | 300 | How old an initData payload may be. |
| Allow Auto-Provisioning | allowAutoProvision | On | Create an account on first Telegram login. |
| Username Prefix | usernamePrefix | tg_ | Fallback prefix for generated usernames. Up to 16 letters, numbers, and underscores. |
| Bot Username | botUsername | Empty | Optional public bot username. |
Bot Token
The token must look like 123456:ABC..., otherwise saving is rejected. After a save, the server calls Telegram getMe with a 5-second timeout and logs the result. A failed call only logs a warning and does not block the save, so check the server log after changing the token.
If no token is stored, login and link requests fail with TELEGRAM_NOT_CONFIGURED (503).
Init-Data Freshness
Telegram stamps each initData payload with an auth_date. The server applies these rules:
| Check | Result on failure | Status |
|---|---|---|
Payload is present and at most 8 KB, with no duplicate keys, and has hash, auth_date, and valid user data | TELEGRAM_INITDATA_MALFORMED | 400 |
auth_date is no older than InitData Max Age and no more than 60 seconds in the future | TELEGRAM_INITDATA_EXPIRED | 401 |
| HMAC-SHA256 hash matches the bot token | TELEGRAM_HASH_INVALID | 401 |
| The same payload has not already been used within the freshness window | TELEGRAM_INITDATA_REPLAYED | 401 |
| The Redis replay store is reachable, when Redis is enabled | TELEGRAM_REPLAY_STORE_UNAVAILABLE | 503 |
InitData Max Age accepts up to 86400. Values above that are rejected on save. Values below 30 are raised to 30.
Replay protection is held in Redis when Redis is enabled, and otherwise in the memory of each server process. On a multi-node deployment, enable Redis so that a payload used on one node can’t be replayed on another.
A rejected payload is logged and recorded as a failed login attempt. Players who see an expired session should close and reopen the Mini App.
Login Behaviour
After initData is verified, the server applies these checks:
| Situation | Result |
|---|---|
| No linked account, Allow Auto-Provisioning off | TELEGRAM_NOT_LINKED (403) |
| Too many login attempts for the account | RATE_LIMIT_EXCEEDED (429) |
| More than 30 login requests per minute from one IP | RATE_LIMITED (429) |
| Account blocked or frozen | AUTHENTICATION_ERROR (401), generic invalid credentials message |
| Account in an admin group | TELEGRAM_ADMIN_FORBIDDEN (403) |
| Account awaiting manual approval | AUTHORIZATION_ERROR (403) |
| Linked account with an unconfirmed email, when your approval method requires email verification | AUTHORIZATION_ERROR (403) |
| Two-factor authentication enabled on the account | The API returns requires2FA and a tempToken. The bundled login button and Mini App page show a message telling the player to use the standard login page. |
The Telegram profile stored for the account (username, name, photo, language, premium status) is refreshed on each completed login.
Admin-Group Restriction
Telegram can never be used to sign in to an account whose group has the permission level a or a1. These users must use the password and admin 2FA flow.
The check runs at login only. Linking is not blocked, so an admin can link a Telegram identity, but that link can’t be used to sign in.
Auto-Provisioned Accounts
When Allow Auto-Provisioning is on, the first login from an unknown Telegram identity creates an account:
- Username: the sanitized Telegram username if it is available, otherwise the prefix plus the Telegram ID, limited to 30 characters.
- Email:
tg_<telegram-id>@telegram.invalid, marked as confirmed. - Password: a random value that the player is never told.
- Group: the default user group.
- Approval: verified immediately, unless your approval method requires manual approval.
If the payload has a start_param, it is processed as an agent and affiliate referral code. First-login bonuses are triggered on the first completed login.
Note: Auto-provisioning does not read the Registration feature toggle. To stop new accounts from Telegram while registration is closed, turn Allow Auto-Provisioning off as well. See Feature Toggles Reference.
Linking and Unlinking
Player Linking
A player with an existing account can link Telegram from their profile:
- Sign in with a password from inside the Mini App.
- Open profile settings and click Link Telegram. The button is disabled outside Telegram.
Each Telegram identity and each account can have one link. A Telegram identity that is already linked returns TELEGRAM_ALREADY_LINKED (409).
Player Unlinking
Click Unlink Telegram in profile settings. The request fails with TELEGRAM_LAST_CREDENTIAL (409) if the account has never had a real password set.
Warning: Auto-provisioned players can’t currently clear this condition themselves. The change-password route asks for the current password, which they were never given, and password reset emails would go to the undeliverable
telegram.invalidaddress.
Admin Unlinking
Open Telegram Accounts in the admin navigation, or go to /admin/plugins/telegram-auth/page/accounts.
- Search by Telegram ID, Telegram username, or username.
- Click Unlink and enter a reason. The default is
Admin unlink.
An admin unlink also revokes the user’s tokens and sessions, and writes an admin audit entry with the Telegram ID, Telegram username, and reason.
Warning: An admin unlink does not check for another credential. An auto-provisioned player who is unlinked loses their only way to sign in.
Link details for a single user also appear in the user detail drawer.
API Endpoints
All routes are active only while the plugin is active. During maintenance mode they return 503, because /api/v1/plugins is not among the paths that bypass it.
| Method | Path | Permission | Description |
|---|---|---|---|
POST | /api/v1/plugins/telegram-auth/login | Public | Verify initData and sign in |
POST | /api/v1/plugins/telegram-auth/link | Authenticated + CSRF | Link the caller’s account |
DELETE | /api/v1/plugins/telegram-auth/link | Authenticated + CSRF | Unlink the caller’s account |
GET | /api/v1/plugins/telegram-auth/status | Authenticated | Caller’s link status |
GET | /api/v1/plugins/telegram-auth/admin/accounts | Admin session | List linked accounts (search, limit, offset) |
DELETE | /api/v1/plugins/telegram-auth/admin/accounts/:userId | Admin session + CSRF | Unlink a user (reason, up to 500 characters) |
POST /login takes { "initData": "...", "mode": "token" | "cookie" }. token is the default and returns tokens in the response body. cookie sets HttpOnly auth cookies and is what the bundled pages use.
Related
- Plugin Management — installing and configuring plugins
- Telegram Stars Payments — deposits, which require a linked Telegram account
- Feature Toggles Reference — Registration and Maintenance Mode