Skip to content

serejaris/telegram-skills / skills/tg-miniapp-launch-auth

tg-miniapp-launch-auth

Verified

Use when choosing how a Telegram Mini App opens (keyboard, inline or menu button, main app, direct link, startapp, join request) or when a server must trust a Mini App user: validating initData by HMAC or Ed25519, signature in the check string, auth_date, isVersionAtLeast gating, origin protection, test environment and debugging.

tg-miniapp-launch-auth

Checked against the official docs on 2026-10-30: Bot API 10.3 (latest, August 24, 2026), Mini Apps page with Recent changes up to 10.1, telegram-web-app.js?64. The Mini Apps page doesn't describe origin protection (see below); the changelog does.

Not verified live

No bot, client or device was used to write this skill. These checks wait for a live Mini App:

  • A fresh initData string with signature from a live bot in 2026. The repository's tests use synthetic vectors, so they prove this code matches the algorithm below, and only a live string proves Telegram still signs that way. We found no public vector for Telegram's Ed25519 key without a real person's data, so that key is untested here.
  • Launch behavior on a real iPhone and Android device. The launch table comes from the docs.
  • Origin protection: what a blocked call looks like, and whether subdomains and redirects count as the Mini App domain.
  • mode=fullscreen in links.

Pick a launch path

PathSet upinitDataHow the app answers
Inline buttonInlineKeyboardButton.web_app, private chats onlyuser, query_idanswerWebAppQuery sends a message on the user's behalf and closes the app
Menu buttonBotFather /setmenubutton, or setChatMenuButton with MenuButtonWebApp for one chatsame as inline buttonsame as inline button
Main Mini AppBotFather, then t.me/<bot>?startapp[=value][&mode=compact]user, chat_type, chat_instance, start_paramown server
Direct linkNamed app in BotFather, then t.me/<bot>/<app>?startapp=value&mode=compactsame as main app; no access to the chatown server; to send a message, send the user back to inline mode
Rich message buttonRichMessageButton.web_app (10.3), private chats onlysame as inline buttonsame as inline button
Join request (10.1)Guard bot: sendChatJoinRequestWebApp on chat_join_requestuser, chat, chat_join_request_query_idanswerChatJoinRequestQuery with approve, decline or queue
Keyboard buttonKeyboardButton.web_app, private chats onlyemptysendData, up to 4096 bytes: the bot gets a web_app_data service message and the app closes
Inline modeInlineQueryResultsButton.web_app in answerInlineQueryempty per WebAppInitDataswitchInlineQuery sends the user back to pick a result

Take the first row that fits. Choose a path with a verifiable user whenever the server needs identity: keyboard and inline mode launches carry none.

The attachment menu is available only to major advertisers on the Telegram Ad Platform; other bots can use it only on the test server. requestChat (9.6) with savePreparedKeyboardButton lets an open app ask the user to pick a chat.

start_param

startapp takes up to 64 characters, A-Z, a-z, 0-9, _ and -; use base64url for binary data. The value arrives in initData.start_param and in the GET parameter tgWebAppStartParam.

  • The GET parameter is unsigned: use it to pick a screen. Anything a server trusts comes from validated start_param.
  • The WebAppInitData table says start_param is returned only for the attachment menu. The main app and direct link sections of the same page say it is passed there too. Follow those sections.

Opening height

The main app and direct links open at full height by default; mode=compact opens them at half height. mode=fullscreen appears only in the MTProto links page, so treat it as unconfirmed for the Bot API docs.

Trust a user on the server

Telegram.WebApp.initData is the only input to validate. initDataUnsafe is a convenience for rendering and proves nothing.

  1. The client sends the raw initData string unchanged, for example Authorization: tma <initData> (a tma.js convention).
  2. The server rejects an empty value. Keyboard and inline mode launches have no identity; don't fall back to initDataUnsafe.
  3. The server validates hash, then auth_date.
  4. The server parses user from the validated fields and stores id in a 64-bit type: it has up to 52 significant bits.

Bot token scheme

secret_key = HMAC_SHA256(key="WebAppData", msg=bot_token), then hash = hex(HMAC_SHA256(key=secret_key, msg=data_check_string)). The check string is all received fields except hash, URL-decoded, sorted by key, as key=value, joined with \n. Compare in constant time.

signature stays in this string. The docs say "all received fields" and don't name it. tma.js excludes only hash (validation.ts:94). On 2026-10-30 a string that tma.js publishes as signed by Telegram (created 2024-12-07) matched only with signature kept. That string names a real person, so it stays out of this repository. Keep the exclusion list to hash alone.

scripts/init_data.py does this with the standard library and no network. It rejects repeated keys, because a duplicated field could mean one thing to the check and another to your code. max_age=0 skips the age check, and now overrides the clock in tests. JSON fields such as user stay strings for you to parse:

from init_data import InitDataError, validate

try:
    fields = validate(raw_init_data, bot_token, max_age=3600)
except InitDataError as error:
    return reject(401, error.code)   # malformed, missing_hash, invalid_hash, invalid_auth_date, expired
user = json.loads(fields['user'])

auth_date

The docs make the check optional and name no limit. tma.js defaults to 86400 seconds. Pick your own limit by the value of the action.

initData is issued once, when the app opens, and carries no nonce. An app left open past your limit starts getting expired, so plan a reopen prompt or issue your own short session after the first validation.

Third party without the token

Share initData and bot_id; the third party verifies signature, an Ed25519 signature in base64url, with Telegram's public key.

  • Check string: <bot_id>:WebAppData\n, then fields except hash and signature, sorted, key=value, joined with \n.
  • Production key: e7bf03a2fa4602af4580703d88dda5bb59f32ed8b02a56c187fe7d34caed242d
  • Test key: 40055058a4ee38156a06562e52eece92a771bcd8346a8c4615cb7376eddf72ec
  • Telegram sends the signature without = padding, and strict base64 decoders reject it. third_party_payload restores it.
  • The standard library has no Ed25519, so third_party_payload only prepares (message, signature) and the check stays with your verifier.
  • The docs require the third party to validate auth_date as well.
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
from init_data import third_party_payload, parse_init_data

message, signature = third_party_payload(raw_init_data, bot_id)
Ed25519PublicKey.from_public_bytes(bytes.fromhex(PRODUCTION_KEY)).verify(signature, message)
auth_date = int(parse_init_data(raw_init_data)['auth_date'])  # check it yourself

Gate features by version

Telegram.WebApp.version is the Bot API version of the user's client. Calling a method above it fails: in telegram-web-app.js requestFullscreen logs to the console and throws WebAppMethodUnsupported.

const app = Telegram.WebApp;
if (app.isVersionAtLeast('8.0')) app.requestFullscreen();

isVersionAtLeast proves the method exists, not that it will work: see the iOS report in ../tg-miniapp-ui/client-pitfalls.md.

Origin protection

Since July 20, 2026 Mini App methods can't be called from origins other than the original Mini App domain. It is on by default for all Mini Apps (changelog, Bot API 10.2).

  • Call every Telegram.WebApp method, openInvoice included, from a page on the Mini App domain.
  • Sites opened by links inside the app lose those methods.
  • A flow that leaves your domain and returns needs a live test: the docs don't define "original domain" for subdomains and redirects.
  • The opt-out lives in the @BotFather Mini App. With it, the bot's owner answers for the app having no links to untrusted sites.

Telegram Serverless

The Mini Apps page lists Telegram.WebApp.Serverless, where the platform validates initData before running a bot's endpoint. Its docs name no access terms or prices, and a practitioner report describes a closed test, so this skill assumes your own server.

Test and debug

Test server login, inspectors per platform and the mock for a plain browser: references/testing-debug.md.

Sources

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall