Telegram Bot - AuthForge

This pattern lets anyone message your bot, but only licensed users get full responses.

Architecture

User sends a message to your bot.
If not licensed, bot asks for a license key.
User submits key in DM/private chat.
Bot validates key with AuthForge and sets hwidOverride = tg:<telegram_user_id>.
If valid, store “licensed” status for that Telegram user.

Why this works

AuthForge treats HWID as an identity string.
tg:<user_id> is stable per Telegram account.
Seat controls (maxHwidSlots) and reset flows still work.

Use user_id, not username (usernames can change). Use heartbeatMode: "LOCAL" (or heartbeat_mode="LOCAL" in Python) for the bot process. Server heartbeat mode targets software running on the licensee’s device; a Telegram bot only performs validation on your infrastructure, so local session checks after login are enough. For every scheduled run or every message, use validateLicense / validate_license (same /auth/validate + Ed25519 verification as login) so you avoid heartbeat timers and never need logout() just to stop background intervals. Keep login for processes that intentionally hold one long-lived session.

Node example (Telegraf-style pseudocode)

import { AuthForgeClient } from "@authforgecc/sdk";

async function validateTelegramKey(telegramUserId, licenseKey) {
  const client = new AuthForgeClient({
    appId: process.env.AUTHFORGE_APP_ID,
    appSecret: process.env.AUTHFORGE_APP_SECRET,
    publicKey: process.env.AUTHFORGE_PUBLIC_KEY,
    heartbeatMode: "LOCAL",
    hwidOverride: `tg:${telegramUserId}`,
  });

  const result = await client.validateLicense(licenseKey);
  return result.valid ? result : { valid: false, code: result.code };
}

Python example

from authforge import AuthForgeClient

def validate_telegram_key(user_id: int, license_key: str) -> dict:
    client = AuthForgeClient(
        app_id=APP_ID,
        app_secret=APP_SECRET,
        public_key=PUBLIC_KEY,
        heartbeat_mode="LOCAL",
        hwid_override=f"tg:{user_id}",
    )
    return client.validate_license(license_key)

Recommended bot behavior

Keep key entry in private chat.
Rate limit invalid attempts per user and per IP.
Return clear error text for invalid_key, expired, revoked, hwid_mismatch.
Provide a support command to request reset help when users switch accounts.

​Architecture

​Why this works

​Node example (Telegraf-style pseudocode)

​Python example

​Recommended bot behavior

​Related

Architecture

Why this works

Node example (Telegraf-style pseudocode)

Python example

Recommended bot behavior

Related