Authenticate a React Telegram Mini App with initData and an App-Issued JWT

In a React Telegram Mini App, send the raw Telegram.WebApp.initData string to your backend and validate it there before treating its user fields as authenticated. After validation, your backend can issue its own session credential, such as a JWT. Telegram does not issue that application JWT as part of the Mini App initData flow.

How do I authenticate a Telegram Mini App user in React?

React collects and forwards launch data; the backend decides whether it is authentic. Telegram says, “You should only use data from initData on your bot’s server and only after it has been validated.” It also warns, “Data from this field should not be trusted,” referring to initDataUnsafe. See Telegram’s Mini Apps documentation.

#	Preview	Product	Price
1		How To Make Money on Telegram: Developing and Monetizing Telegram Mini Apps and Bots	$11.99	Buy on Amazon

As an Amazon Associate I earn from qualifying purchases.

Read window.Telegram.WebApp.initData and send that raw string to an application endpoint. Do not authenticate based on a user ID, name, or other value copied from initDataUnsafe. The object can be useful for rendering interface details, but the browser cannot establish that those values came from Telegram.

async function authenticateTelegramMiniApp() {
  const initData = window.Telegram?.WebApp?.initData;

  if (!initData) {
    throw new Error("Telegram launch data is unavailable");
  }

  const response = await fetch("/api/auth/telegram-mini-app", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    credentials: "include",
    body: JSON.stringify({ initData })
  });

  if (!response.ok) {
    throw new Error("Telegram authentication failed");
  }

  return response.json();
}

This example forwards the string; it does not validate it. Use your application’s normal protected transport, such as HTTPS. Never put the bot token in the React bundle or send it to the browser: the documented Mini App HMAC validation is performed by the bot server.

#1 Best Overall

How To Make Money on Telegram: Developing and Monetizing Telegram Mini Apps and Bots

$11.99

Buy on Amazon

Handle missing launch data

Telegram documents that initData can be empty in some launch modes. Treat a missing value as unauthenticated rather than assuming there is always a user object. Return an appropriate unauthenticated response and provide a supported way to launch or authenticate into the app.

How do I validate Telegram Mini App initData?

For a Mini App authenticated by its bot’s backend, Telegram’s documented method uses the received hash and an HMAC key derived from the bot token. Validate the original received fields before using them to identify a user or issue a session.

1. Parse the raw query string carefully. Preserve the received field values needed for verification. Do not build the verification input from client-parsed display data.
2. Build the data-check-string. Exclude the hash field, sort the remaining received fields alphabetically by key, render each as key=value, and join the lines with a line-feed (LF) character.
3. Derive the secret key in the specified order. Calculate HMAC-SHA-256 with WebAppData as the HMAC key and the bot token as the message. In notation, secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).
4. Calculate and compare the hash. Calculate HMAC-SHA-256 over the data-check-string using the derived secret key, encode the result as the expected hexadecimal representation, and compare it with the received hash. Reject a mismatch.
5. Check freshness. Read auth_date and reject data older than the maximum age your application accepts. Telegram recommends checking freshness but does not set one universal age limit in the cited Mini Apps instructions. Choose a policy that fits your app, and consider replay and session controls appropriate to its risks.
6. Only then use the verified fields. Derive the authenticated Telegram user identity from the successfully verified data and apply your own authorization rules.

Use a maintained cryptographic library and a query-string parser whose behavior you understand. The algorithm is specified by Telegram, but framework, parser, and library choices are application decisions; test your implementation independently.

How does an application JWT fit after validation?

Once the backend has validated Mini App launch data and identified the user, it may create an application session. A JWT in this design is signed by your application, not Telegram; it is not the initData string and does not replace initData validation.

Define the session policy on the server: keep the signing key server-side, include only claims the application needs, set an expiry, and decide how renewal and revocation work. Choose browser storage deliberately. An HTTP-only, secure cookie can reduce exposure to JavaScript, while cookie-based sessions require appropriate cross-site request protections. If using another storage approach, account for the risk of script access. These are application security choices, not Telegram requirements.

When a later request presents your JWT, validate it according to your own issuer, signature, audience, expiry, and revocation policy. Validate a fresh Telegram initData assertion when the user is establishing or re-establishing a Telegram launch session; do not treat possession of an old app JWT as proof that newly received launch data is valid.

Which Telegram validation flow should you use?

Mini App HMAC, Mini App Ed25519, Telegram Login OIDC, and the Login Widget are distinct protocols. Select the one matching the integration rather than applying one flow’s data-check-string or token rules to another.

Optional third-party verification with Ed25519

Telegram documents a separate Mini App verification route for a service that should not receive the bot token. Its data-check-string begins with <bot_id>:WebAppData, followed by LF and then the received fields except hash and signature, sorted alphabetically and rendered as key=value lines. Verify the base64url-encoded Ed25519 signature with the corresponding Telegram public key and check auth_date. Do not reuse the HMAC data-check-string for this route. The procedure and keys are documented on Telegram’s Mini Apps page.

OIDC ID tokens and the Login Widget are not Mini App initData

For Telegram Login OIDC, validate the ID token’s signature, issuer (https://oauth.telegram.org), expected audience (your Bot ID), and expiry; follow the documented server-side code exchange, state, and PKCE guidance when using that flow. These are OIDC rules, not an alternative recipe for Mini App initData. Telegram’s login documentation describes the flow.

The Telegram Login Widget is another separate option with its own authorization-data validation recipe. Its HMAC secret construction differs from the Mini App method; do not substitute it for Mini App validation. See Telegram’s Login Widget documentation.

What should I check when validation fails?

• Confirm the frontend sends initData, not initDataUnsafe.
• Confirm the bot token exists only on the backend.
• Check that the HMAC key/message order is correct, fields are sorted by key, hash is excluded, and lines use LF separators.
• Reject a mismatched hash and data outside your application’s accepted auth_date window.
• Ensure you are not using the Login Widget’s different HMAC recipe for Mini App data.
• Handle empty initData as unauthenticated rather than inferring a user identity from client-side fields.
• If the integration is Telegram Login OIDC, validate its ID token under OIDC rules instead of applying Mini App HMAC logic.

Telegram’s Mini Apps documentation lists Bot API 10.1 dated June 11, 2026, in its recent changes, alongside later version-history entries. The validation guidance is platform-wide rather than country-specific; check the live Mini Apps documentation for current API details.

Quick Recap

Bestseller No. 1

How To Make Money on Telegram: Developing and Monetizing Telegram Mini Apps and Bots

$11.99

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.