When building a Telegram Mini App, front-end context is provided through the window.Telegram.WebApp object. Developers often inspect window.Telegram.WebApp.initDataUnsafe to retrieve the current user's Telegram ID, first name, and username. Using initDataUnsafe to identify users in your API endpoints introduces a massive security vulnerability. Any client can open browser Developer Tools, alter the JavaScript memory state, replace initDataUnsafe.user.id with another user's ID, and trigger API calls. If your PHP backend trusts client-provided IDs without verification, attackers can hijack accounts, spend other users' balances, or manipulate state arbitrarily.

To secure your application, your backend must process the raw, encrypted query string provided by window.Telegram.WebApp.initData. This string includes a cryptographic hash generated by Telegram's servers. By running a server-side HMAC validation check against your Telegram Bot Token, you can verify that the payload was authored by Telegram and has not been tampered with by the client.

This guide demonstrates how to break down raw initData strings in PHP, derive the secret verification key, perform timing-safe hash comparisons, and enforce strict expiration windows on auth_date timestamps.

The Vulnerable Code Path: Trusting Unverified Client Input

Consider an e-commerce Mini App processing an order. The frontend reads the user ID from initDataUnsafe and sends it in a JSON POST payload to a PHP script.

<?php // BAD PRACTICE: Accepting unverified user_id from client payload header('Content-Type: application/json'); $rawInput = file_get_contents('php://input'); $data = json_decode($rawInput, true); $userId = $data['user_id'] ?? null; $cartId = $data['cart_id'] ?? null; if (!$userId || !$cartId) { http_response_code(400); echo json_encode(['error' => 'Missing parameters']); exit; } // The backend blindly executes logic on behalf of $userId $orderId = processOrderForUser($userId, $cartId); echo json_encode(['success' => true, 'order_id' => $orderId]);

In this scenario, an attacker simply executes fetch('/api/order.php', { method: 'POST', body: JSON.stringify({ user_id: 999999, cart_id: 42 }) }) directly from the web console. The server executes the order under victim user 999999.

To prevent this, the client must send the raw window.Telegram.WebApp.initData string—typically inside an Authorization HTTP header—and the server must validate it before reading any nested user payload.

Constructing the HMAC Verification Pipeline in PHP

Telegram generates the hash field within initData using a multi-step HMAC-SHA256 algorithm:

  1. The raw input string (formatted like key1=value1&key2=value2&hash=1234...) is split into individual key-value pairs.
  2. The hash pair is removed from the list.
  3. All remaining key-value pairs are sorted alphabetically by key.
  4. The sorted pairs are joined with newline characters (\n) to form the data_check_string (e.g., auth_date=1600000000\nuser=...).
  5. A secret key is derived by calculating an HMAC-SHA256 signature using the constant string "WebAppData" as the key and your Telegram Bot Token as the message.
  6. The final verification hash is calculated by taking the HMAC-SHA256 of the data_check_string using the derived secret key.
  7. The computed hash is compared to the provided hash value.

A common mistake in PHP implementation is relying on parse_str(). The parse_str() function automatically parses and URL-decodes query string values, converting JSON strings like user={"id":123} into nested PHP arrays. Reconstructing the data_check_string after parse_str() mutates key order and encoding, causing hash calculation mismatches. Instead, you must manually parse the string while decoding values cleanly.

Here is a complete, standalone PHP function that safely implements this validation logic:

<?php declare(strict_types=1); /** * Validates Telegram Mini App initData string. * * @param string $initData Raw initData string from window.Telegram.WebApp.initData * @param string $botToken The Telegram Bot Token issued by @BotFather * @return array{is_valid: bool, data: array<string, mixed>, error: ?string} */ function validateTelegramInitData(string $initData, string $botToken): array { if (empty($initData)) { return ['is_valid' => false, 'data' => [], 'error' => 'Empty initData']; } // Split string by ampersand into individual key-value pairs $pairs = explode('&', $initData); $hash = null; $dataDict = []; foreach ($pairs as $pair) { $parts = explode('=', $pair, 2); if (count($parts) !== 2) { continue; } $key = urldecode($parts[0]); $value = urldecode($parts[1]); if ($key === 'hash') { $hash = $value; } else { $dataDict[$key] = $value; } } if ($hash === null) { return ['is_valid' => false, 'data' => [], 'error' => 'Hash parameter missing']; } // Step 1: Sort all keys alphabetically ksort($dataDict); // Step 2: Form data_check_string by joining key=value pairs with newlines $checkPairs = []; foreach ($dataDict as $key => $value) { $checkPairs[] = $key . '=' . $value; } $dataCheckString = implode("\n", $checkPairs); // Step 3: Compute secret key using HMAC-SHA256("WebAppData", bot_token) $secretKey = hash_hmac('sha256', $botToken, 'WebAppData', true); // Step 4: Compute data hash using HMAC-SHA256(secret_key, data_check_string) $calculatedHash = hash_hmac('sha256', $dataCheckString, $secretKey); // Step 5: Timing-safe string comparison if (!hash_equals($calculatedHash, $hash)) { return ['is_valid' => false, 'data' => [], 'error' => 'Invalid signature match']; } // Decode JSON objects inside the validated data dict (e.g., 'user', 'receiver') $parsedData = []; foreach ($dataDict as $key => $value) { if ($key === 'user' || $key === 'receiver' || $key === 'chat') { $parsedData[$key] = json_decode($value, true) ?? $value; } else { $parsedData[$key] = $value; } } return ['is_valid' => true, 'data' => $parsedData, 'error' => null]; }

Notice the use of hash_equals() instead of standard string equality (== or ===). Standard equality operators exit immediately upon encountering the first mismatched character. This introduces measurable execution time variations that allow attackers to deduce valid hash signatures byte by byte through side-channel timing attacks. hash_equals() runs in constant time regardless of string match location.

Blocking Replay Attacks with auth_date Checks

Validating signatures proves that an initData string was originally generated by Telegram for your specific bot. However, signature validation alone does not prevent replay attacks. If an attacker intercepts a legitimate user's valid initData string, they can store and replay that exact payload indefinitely unless you enforce temporal expiration limits.

Telegram includes an auth_date parameter inside initData, which contains the Unix timestamp of when the signature was generated. Your server must inspect auth_date and reject payloads older than your defined threshold (e.g., 24 hours or 86,400 seconds).

Here is an extended production validator that enforces timestamp freshness and verifies the presence of required fields:

<?php declare(strict_types=1); class TelegramDataValidator { private string $botToken; private int $maxLifetimeSeconds; public function __construct(string $botToken, int $maxLifetimeSeconds = 86400) { $this->botToken = $botToken; $this->maxLifetimeSeconds = $maxLifetimeSeconds; } public function authenticateRequest(string $initData): array { $result = validateTelegramInitData($this->initDataValidationWrapper($initData), $this->botToken); if (!$result['is_valid']) { throw new Exception('Authentication failed: ' . $result['error'], 401); } $data = $result['data']; // Enforce auth_date presence if (!isset($data['auth_date']) || !is_numeric($data['auth_date'])) { throw new Exception('Authentication failed: Missing auth_date', 401); } $authTimestamp = (int)$data['auth_date']; $currentTime = time(); // Check for future timestamps (clock skew guard) if ($authTimestamp > ($currentTime + 60)) { throw new Exception('Authentication failed: Timestamp in future', 401); } // Reject stale payloads if (($currentTime - $authTimestamp) > $this->maxLifetimeSeconds) { throw new Exception('Authentication failed: Credentials expired', 401); } // Ensure identity exists if (!isset($data['user']['id'])) { throw new Exception('Authentication failed: No user identity found', 401); } return $data; } private function initDataValidationWrapper(string $raw): string { // Clean bearer prefixes if passed directly from HTTP headers if (str_starts_with($raw, 'Bearer ')) { return substr($raw, 7); } return $raw; } }

Setting $maxLifetimeSeconds to 86400 allows users to keep the Mini App open for up to 24 hours without breaking their session. For sensitive operations (such as performing financial transactions or retrieving API keys), reduce this threshold to 3600 seconds (1 hour) or force the application to refresh authentication state.

Intercepting Headers and Securing PHP API Endpoints

To connect this logic to your client app, pass the raw initData string from JavaScript via standard fetch requests. Sending authentication tokens via custom headers (such as Authorization or X-Telegram-Init-Data) is cleaner and safer than appending strings to URL parameters, which can leak into server access logs.

Frontend Initialization (JavaScript) 

async function apiRequest(endpoint, payload = {}) { // Obtain raw initData directly from Telegram JS SDK const initData = window.Telegram?.WebApp?.initData; if (!initData) { throw new Error("Mini App context missing"); } const response = await fetch(endpoint, { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${initData}` }, body: JSON.stringify(payload) }); if (!response.ok) { const err = await response.json(); throw new Error(err.error || "Request failed"); } return await response.json(); }

Server-Side Route Handler (PHP)

Now, implement the production request handler in PHP to securely extract identity details from the verified initData string:

<?php declare(strict_types=1); require_once __DIR__ . '/TelegramDataValidator.php'; header('Content-Type: application/json'); // Retrieve HTTP authorization headers $headers = getallheaders(); $authHeader = $headers['Authorization'] ?? $headers['authorization'] ?? ''; $botToken = getenv('TELEGRAM_BOT_TOKEN'); if (!$botToken) { http_response_code(500); echo json_encode(['error' => 'Server configuration error']); exit; } $validator = new TelegramDataValidator($botToken, 86400); try { // Authenticate and retrieve parsed Telegram data $validatedPayload = $validator->authenticateRequest($authHeader); // Access verified user properties $telegramUser = $validatedPayload['user']; $telegramUserId = (int)$telegramUser['id']; $firstName = $telegramUser['first_name'] ?? ''; // Process request payload securely bound to $telegramUserId $inputData = json_decode(file_get_contents('php://input'), true) ?? []; // Example response using authenticated user echo json_encode([ 'success' => true, 'authenticated_as' => [ 'id' => $telegramUserId, 'first_name' => $firstName ], 'data' => $inputData ]); } catch (Exception $e) { $statusCode = $e->getCode() >= 400 && $e->getCode() < 600 ? $e->getCode() : 401; http_response_code($statusCode); echo json_encode([ 'success' => false, 'error' => $e->getMessage() ]); exit; }

Production Integration Edge Cases

When deploying Mini Apps to production, keep these integration realities in mind:

  1. Environment Variables: Never hardcode your Telegram Bot Token in your codebase. Load it via getenv('TELEGRAM_BOT_TOKEN') or your framework's secret management layer.
  2. WebApp.ready() Timing: Do not invoke UI components like window.Telegram.WebApp.MainButton.show() until your initial authentication request completes successfully on the backend. Showing interactive elements before validating identity leads to broken application states if backend validation rejects the session.
  3. String Encoding Anomalies: Telegram sends JSON strings inside initData encoded using UTF-8 sequences (e.g., escaped unicode characters like \u0026). Manually manipulating or double-decoding strings will alter byte representations and invalidate HMAC checks. Process keys and values exactly as they are split from the string.

If you need custom bot development or specialized Mini App architecture for high-volume environments, work with BotCreator — a studio that ships production Telegram bots and Mini Apps.