What Is a Telegram Session File? .session, String Sessions, .json and tdata Explained

2026-11-06 · 5 min

A Telegram session file stores your account's auth key so a tool can log in without a code. Learn the Telethon and Pyrogram formats and how to move one safely.

A Telegram session file is a small file that stores a logged-in Telegram session: the account's authorization key plus the address of the Telegram data center it talks to. Any program holding that file can act as the account without asking for a login code or password. That makes it useful for moving your own accounts between tools, and dangerous if it leaks. Treat it exactly like a password.

What's inside a .session file

When an app logs in to Telegram, it agrees on a 2048-bit authorization key with Telegram's servers. Telegram remembers that key as a logged-in device. As long as the app keeps the key, it can reconnect without a new code.

The Telethon docs describe the default .session file as an SQLite database that "contain[s] the required information to talk to the Telegram servers": the server IP, the port and the authorization key. By default it also caches the users and chats the client has seen. Pyrogram uses the same idea, a single SQLite .session file, and notes that a session is "uniquely bound to your own account, indefinitely".

The two libraries use different table layouts, so a Telethon file is not automatically a Pyrogram file, even though both end in .session.

The formats you'll run into

Format	What it is	Typical use
Telethon `.session`	SQLite file with DC, server, port, auth key	Python scripts and tools
Pyrogram `.session`	SQLite file, different schema	Pyrogram-based tools
String session	The same key exported as one line of text	Servers without persistent disk, config files
`.json` sidecar	api_id, device model, system and app version, language	Exports from multi-account tools
tdata	Telegram Desktop's local data folder	The official desktop app

String sessions. Telethon calls a StringSession "a way to export your authorization key". The docs add a fair warning: "it is easier to leak a string than it is to leak a file." A string pasted into a chat or a ticket is a full login.

The .json sidecar. This isn't a Telegram standard. It's a convention many tools follow: a JSON file with the same name as the .session, recording which app id and device parameters the session was created with. Keeping the pair together lets the session keep presenting the same app and device details after a move.

tdata. This is the folder Telegram Desktop keeps on your computer. It's a desktop-app format, not a Telethon or Pyrogram session. Telegramte does not import tdata. It imports .session, .json, string sessions and .zip archives of them.

Security rules for session files

Never run one session in two places at once

This is the most common way to lose a session. If two programs, or two IP addresses, send requests with the same authorization key in parallel, Telegram notices. Per the Telegram API error reference, the server returns AUTH_KEY_DUPLICATED, and at that point "the session was already invalidated by the server and the user must generate a new auth key and login again."

The safe way to move a session:

Stop the account in the old tool, or shut that tool down.
Copy the .session file (and its .json, if there is one).
Import it into the new tool and run it only there.
Don't start the same file in the old tool again.

How to revoke a session

Deleting a leaked file does nothing: the key is still valid on Telegram's side. Open Telegram on your phone, go to Settings → Devices, tap the session you don't recognize and terminate it. The Telegram FAQ gives the same path for lost devices. On the same screen you can choose to automatically terminate sessions that have been inactive for a set period.

Turn on two-step verification too. After you terminate a stolen session, the password stops anyone from simply logging back in with an SMS code.

How to import session files into Telegramte

Go to Numbers → Connect number and open the Session file tab.
Select your .session files, plus the matching .json files if you have them. For many accounts, upload a single .zip. You can also paste a string session.
Optionally pick a proxy. If you don't, a working, least-used proxy from your pool can be assigned automatically.
Each file is checked individually. Valid accounts appear in your numbers list; anything that fails is listed with the reason.

Session keys are stored encrypted with AES-256-GCM. Once the import is done, move the original files somewhere safe or delete them.

FAQ

My session file stopped working. Is the account banned? Not necessarily. The session may have been terminated from Devices, invalidated by AUTH_KEY_DUPLICATED, or closed after a long time unused. Log in on your phone and check.

Does the session file contain my 2FA password? No, but it doesn't need to: the key alone skips the login. That's why it's as sensitive as the password.

Can I convert Telethon to Pyrogram? Third-party converters exist, but every converter you run gets your auth key. Prefer a tool that reads both formats directly. Telegramte does.