Skip to content

Telegram Web App Auth

Validate Telegram Mini App initData in Python with a small, typed, security-focused package.

telegram-webapp-auth implements the validation algorithms from the official Telegram Mini Apps documentation and returns structured dataclasses for users, chats, and init data.

  • Bot-token validation

    Use TelegramAuthenticator.validate() when your backend owns the bot token and receives initData from your Mini App frontend.

  • Third-party validation

    Use TelegramAuthenticator.validate_third_party() when you only know the bot ID and need Telegram's Ed25519 signature flow.

  • Expiry checks

    Pass expr_in to reject stale init data and protect endpoints from replayed payloads.

  • Typed Python API

    Work with WebAppInitData, WebAppUser, and WebAppChat objects instead of raw query strings.

Install

pip install telegram-webapp-auth

poetry add telegram-webapp-auth

uv add telegram-webapp-auth

Quick Example

from datetime import timedelta

from telegram_webapp_auth.auth import TelegramAuthenticator
from telegram_webapp_auth.auth import generate_secret_key
from telegram_webapp_auth.errors import ExpiredInitDataError
from telegram_webapp_auth.errors import InvalidInitDataError

bot_token = "123456:ABC-DEF"
secret_key = generate_secret_key(bot_token)
authenticator = TelegramAuthenticator(secret_key)

try:
    init_data = authenticator.validate(
        init_data=request.headers["Authorization"],
        expr_in=timedelta(minutes=5),
    )
except ExpiredInitDataError:
    raise PermissionError("Telegram init data has expired")
except InvalidInitDataError:
    raise PermissionError("Telegram init data is invalid")

telegram_user = init_data.user

Choosing the right validator

Use validate() for the standard Mini App backend flow with your bot token. Use validate_third_party() when you validate data for third-party use with a bot ID and Telegram public key signature.

Documentation Map