iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To authenticate a Telegram Mini App user in React, send the raw Telegram.WebApp.initData string to your backend and validate it there before identifying the user. Do not use initDataUnsafe as proof of identity: Telegram warns that its data should not be trusted. After successful validation, your backend may issue an application JWT as its own session credential; Telegram does not issue that JWT as part of the Mini App validation algorithm. Telegram’s Mini Apps documentation describes the validation rules.
How do I authenticate a Telegram Mini App user in React?
React collects the launch data; your backend decides whether it is authentic. The browser can use parsed Telegram details for display, but those values do not establish a trusted user identity.
- Read
window.Telegram.WebApp.initDatawhen the app is running inside Telegram. - Send that raw string to an authenticated application endpoint over HTTPS.
- On the server, validate the string using the Mini App HMAC procedure and enforce your own freshness policy.
- Only after verification, use the validated fields to identify the Telegram user and apply your authorization rules.
- If appropriate, issue an application session credential, such as your own JWT.
Telegram states: “You should only use data from initData on your bot’s server and only after it has been validated.” The same documentation says of initDataUnsafe: “Data from this field should not be trusted.” Telegram Mini Apps
React: transmit initData, not a client-side identity claim
const initData = window.Telegram?.WebApp?.initData ?? "";
const response = await fetch("/api/telegram/session", {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: "include",
body: JSON.stringify({ initData }),
});
if (!response.ok) {
throw new Error("Telegram authentication failed");
}This example sends the string without parsing or modifying it. An empty string can occur in some Telegram launch modes; treat missing data as unauthenticated and provide a supported launch or sign-in path rather than assuming a Telegram user object is always available. Telegram documents the launch behavior and initData field.
#1 Best Overall
The bot token must remain on the backend. Never put it in the React bundle, browser storage, or a request made by the browser. The documented Mini App HMAC derivation requires that secret and is intended for bot-server validation.
How do I validate Telegram Mini App initData?
For the bot’s own backend, Telegram specifies an HMAC-SHA-256 check. The incoming initData is a query string. Parse its fields carefully, excluding hash from the data-check-string; sort the remaining received fields alphabetically by key; render each as key=value; and join the lines with a line-feed (LF) character.
- Parse the raw query string. Preserve the field values used for verification. Do not authenticate from a separately supplied, client-parsed object.
- Build the data-check-string. Exclude
hash, sort the other received fields by key, format them askey=value, and join them with LF separators. - Derive the secret key. Compute HMAC-SHA-256 with the bot token as the message and the literal
WebAppDataas the HMAC key:secret_key = HMAC_SHA256(key="WebAppData", message=bot_token). - Calculate the expected hash. Compute HMAC-SHA-256 over the data-check-string using the derived secret key, then represent the result as hexadecimal to compare with the received
hash. - Reject a mismatch. Do not create an authenticated session or use the supplied identity fields if verification fails.
- Enforce freshness. Parse
auth_dateand reject data older than the maximum age chosen by your application. - Use the verified fields. Only now may the backend rely on the Telegram-provided launch data for account identification and subsequent authorization.
Follow Telegram’s precise key/message order and field construction; swapping the HMAC key and message produces a different result. Use a maintained cryptographic library and a careful query-string parser. Telegram specifies the algorithm, not a particular JavaScript package or backend framework, so validate an implementation with independent test cases before relying on it. Official Mini App validation procedure
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Freshness is an application policy
Telegram recommends checking auth_date, but the cited Mini Apps instructions do not mandate a universal maximum age. Set a window appropriate to your launch and session design, account for clock handling, and reject timestamps outside that policy. Replay controls or server-side session protections may also be appropriate; Telegram’s documented validation recipe does not prescribe a universal replay cache.
Can I trust initDataUnsafe?
No—not as an authentication assertion. The object is convenient for client-side display, but it is supplied to the web app in the browser and must not determine who is logged in. Send the raw initData string to the server, verify its signature material there, and derive the authenticated identity only from fields that pass server validation.
How do I validate Telegram initData with a JWT?
There are two separate steps, not one combined Telegram algorithm: validate Telegram’s Mini App launch data, then optionally create a session token under your application’s rules. A JWT your backend issues is an application credential. It is not the Telegram initData string, and Telegram does not sign or issue it through the Mini App HMAC procedure.
Decide the app’s JWT policy
- Sign tokens with an application-controlled key that is stored server-side, never in React.
- Include only claims your application needs, such as an internal subject identifier and relevant authorization context.
- Set an expiry appropriate to the session and define how refresh or revocation works if your app needs those capabilities.
- Choose browser storage deliberately. An HttpOnly, Secure cookie with appropriate SameSite and CSRF protections is one possible design; a bearer token design has different exposure and handling trade-offs.
- Validate the application JWT on protected backend requests. A JWT does not make unverified Telegram launch data trustworthy or eliminate the need to validate a new Telegram assertion when your flow requires one.
Telegram’s documentation does not select a JWT library, expiry, refresh strategy, or browser storage mechanism for your app. Those are application security decisions, not Telegram requirements.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallWhich Telegram authentication flow should I use?
Mini App HMAC validation, optional third-party Ed25519 verification, Telegram Login OIDC, and the Login Widget are separate protocols. Choose the procedure that matches how the user entered your product; do not apply one flow’s data-check-string or token checks to another.
Best Value
| Flow | Use case | Verification material | Boundary |
|---|---|---|---|
| Mini App HMAC | Your bot’s backend validates a Mini App launch | hash; sorted fields excluding hash; HMAC-SHA-256 secret derived from the bot token and WebAppData; auth_date freshness |
Keep the bot token on the backend. Telegram Mini Apps |
| Mini App Ed25519 | A third party must verify Telegram-origin launch data without receiving the bot token | signature; bot-ID-prefixed data-check-string; Telegram Ed25519 public key; auth_date |
Use the distinct signature construction and the public key for the correct environment. Telegram Mini Apps |
| Telegram Login OIDC | A website uses Telegram’s OAuth/OIDC login flow | Signed id_token; validate signature, issuer, expected audience, and expiry; authorization-code flow also uses state, with PKCE S256 recommended |
Separate login protocol; do not validate its ID token with Mini App HMAC rules. Telegram Login |
Third-party Ed25519 verification
Telegram documents a separate route for a service that should not receive the bot token. The signature path uses the signature parameter and a different data-check-string: start with <bot_id>:WebAppData, add LF, then include all received fields except hash and signature, sorted alphabetically and rendered as key=value lines. Verify the base64url Ed25519 signature with Telegram’s published public key for the matching production or test environment, and check auth_date. Do not reuse the HMAC data-check-string for this path. Telegram’s Ed25519 instructions
OIDC and the Login Widget are not Mini App validation
For Telegram Login OIDC, Telegram documents an id_token JWT flow with issuer https://oauth.telegram.org, expected audience (the Bot ID), expiry, and signature validation. Its authorization-code guidance also covers state and recommends PKCE S256. These rules apply to OIDC—not Mini App initData. Telegram Login documentation
The Telegram Login Widget has yet another HMAC recipe. Do not use its SHA256(bot token)-based secret construction for Mini App launch data. Telegram Login Widget validation
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →What should I check when validation fails?
- Confirm the browser sends
initData, notinitDataUnsafeor a client-built identity object. - Confirm the bot token is available only to the backend and has not entered the React bundle or browser requests.
- Recheck alphabetical sorting, exclusions, exact field values, LF separators, and the HMAC key/message order.
- Reject a hash mismatch and apply the application’s
auth_datefreshness rule. - Verify that the endpoint receives the raw query string intact and that its parser handles encoded values correctly.
- Handle empty
initDataas unauthenticated rather than assuming every launch includes user data. - If the product uses OIDC, validate the ID token under OIDC rules; if it uses the Login Widget, follow that widget’s separate validation procedure.
Telegram’s official Mini Apps documentation lists Bot API 10.1 among its version history dated June 11, 2026, alongside later history entries. Its validation guidance is platform-wide rather than country-specific; consult the live documentation when implementing against the current API. Telegram Mini Apps documentation and version history
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
