Telegram api_id and api_hash: getting them, security and rules

What are api_id and api_hash?

How to get an api_id on my.telegram.org

1. 1

   Sign up in an official app

   Telegram requires an account created through an official Telegram app. Use an active number you own — Telegram sends important developer notifications to it.

2. 2

   Log in to my.telegram.org

   Open https://my.telegram.org, enter the number in international format (+1..., +998...) and type the confirmation code you receive.

3. 3

   Open “API development tools”

   This section holds the form for creating an application.

4. 4

   Fill in the form

   Enter the app title, short name and the remaining fields. Per the ToS, the title must not contain “Telegram” (unless preceded by “Unofficial”), and you can't use the official Telegram logo.

5. 5

   Store api_id and api_hash

   The page shows your api_id, api_hash and MTProto server addresses. Keep the keys out of code: use TELEGRAM_API_ID and TELEGRAM_API_HASH environment variables or a secrets manager.

6. 6

   Connect in Socialift (optional)

   In the dashboard, add api_id and api_hash under Keys (Kalitlar) → Telegram; they are stored encrypted and checked against Telegram. Then connect the account under Connections (Ulanishlar) → Telegram account: phone → code → 2FA password if enabled.

Telegram API Terms of Service: what matters

Key points from the official “Creating your Telegram Application” page and the API Terms of Service.

Login flow: phone → code → 2FA password

In a web app, login spans two HTTP requests. The phone_code_hash from step one is only valid inside the same intermediate session, so pass both to step two.

import os
from socialift import TelegramAccount

API_ID = int(os.environ["TELEGRAM_API_ID"])
API_HASH = os.environ["TELEGRAM_API_HASH"]

async def start_login(phone: str) -> dict:
    async with TelegramAccount(api_id=API_ID, api_hash=API_HASH) as tg:
        return await tg.send_code(phone)  # phone_code_hash + intermediate session

async def finish_login(phone: str, code: str, sent: dict, password: str | None = None) -> str:
    async with TelegramAccount(api_id=API_ID, api_hash=API_HASH,
                               session=sent["session"]) as tg:
        result = await tg.sign_in(phone, code, phone_code_hash=sent["phone_code_hash"])
        if result["two_factor_required"]:
            result = await tg.sign_in_password(password)
        return tg.export_session()  # as sensitive as a password — encrypt it

Reconnecting with a stored session

import os
from socialift import TelegramAccount

async def get_account() -> TelegramAccount:
    tg = TelegramAccount(api_id=int(os.environ["TELEGRAM_API_ID"]),
                         api_hash=os.environ["TELEGRAM_API_HASH"],
                         session=os.environ["TELEGRAM_SESSION"])
    await tg.connect()
    if not await tg.is_authorized():
        await tg.disconnect()
        raise RuntimeError("Session revoked — log in again")
    return tg

Storing the session string safely

The string from export_session() grants full account access — no code, password or 2FA needed.

• ▸Store it encrypted at rest (for example with KMS or a dedicated encryption key), and keep the key away from the database.
• ▸Never write the session to logs, error trackers or the browser.
• ▸Don't use one session in two processes at once: parallel main connections for one authorization trigger AUTH_KEY_DUPLICATED, which invalidates the session and forces a new login.
• ▸One session per account; don't copy a single string across servers.
• ▸Close unused sessions with log_out(); review and terminate unknown devices with sessions() and reset_session().
• ▸Other sessions get a notification on every new login — tell the account owner in advance.

Ban and FLOOD_WAIT risk: responsible use

Handling FLOOD_WAIT

import asyncio
from socialift import RateLimitError

async def send_report(tg, text: str) -> None:
    try:
        await tg.send_message("@my_group", text)
    except RateLimitError as exc:        # Telegram: FLOOD_WAIT_X
        if (exc.retry_after or 0) > 300:
            raise                          # long wait — reschedule the job
        await asyncio.sleep(exc.retry_after or 5)
        await tg.send_message("@my_group", text)