telegram-webapp-auth

telegram-webapp-auth validates Telegram Mini App initData in Python.

It implements Telegram's official Mini Apps authentication algorithms, supports both bot-token and third-party validation flows, and returns typed dataclasses for users, chats, and init data.

Features

• Bot-token validation with TelegramAuthenticator.validate()
• Third-party Ed25519 validation with TelegramAuthenticator.validate_third_party()
• Optional expiry checks with expr_in
• Typed WebAppInitData, WebAppUser, and WebAppChat results, with unknown top-level fields preserved
• Python 3.10+ support
• Lightweight runtime dependency set

Installation

pip install telegram-webapp-auth
# or
poetry add telegram-webapp-auth
# or
uv add telegram-webapp-auth

Quick Start

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

secret_key = generate_secret_key("123456:ABC-DEF")
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

Documentation

Read the full documentation at swimmwatch.github.io/telegram-webapp-auth.

Useful starting points:

• Installation
• Quick start
• Third-party validation
• API reference

Maintenance And Security

This project is in maintenance mode and accepts bug fixes. Please report security issues privately; see SECURITY.md.

License

telegram-webapp-auth is licensed under the MIT License.