Developers tend to file Telegram credentials under “config values”: paste them into a .env file, push the prototype, move on. That habit is risky, because some of those strings do far more than identify an app. A leaked session file can be as good as someone’s phone in an attacker’s hand. This checklist sorts Telegram’s credentials by what they can actually do if stolen, then covers storage, two-factor authentication, revocation and the session list nobody remembers to check.
Telegram does not hand out one secret, it hands out several, and they carry very different levels of risk. A bot token from BotFather controls a bot. An api_id and api_hash pair from my.telegram.org identifies an application built on the MTProto client API. And once a real user logs in through that application, a session is created that grants access to the whole account. If you still need to obtain these values, this step-by-step guide to getting a telegram api key walks through each path. This article picks up where that one stops: what to protect, how, and what to do on the day something leaks.
Rank your secrets by blast radius
Before deciding where each value lives, be honest about what an attacker could do with it.
- The bot token. Anyone holding it can operate the bot: read the messages users send to it, reply as it, change its webhook to point at their own server. Serious, but limited to the bot’s own reach.
- The api_id and api_hash. These identify your application to Telegram’s servers. On their own, they do not log anyone in, because a user still has to authorize the app with a login code or a QR scan. A leak lets someone impersonate your app, and if they publish it, abuse attributed to your api_id becomes your problem. Telegram also allows only one api_id per phone number, so this pair is not something you can casually regenerate across projects.
- The session. This is the crown jewel. After a successful login, MTProto libraries persist an authorization key, often as a .session file or an exported session string. Whoever holds it is logged in as that user, with access to private chats and contacts, and two-factor authentication does not stand in the way, because the password check already happened when the session was created.
The practical rule follows directly: treat a session file exactly like a password plus a second factor, because functionally that is what it is.
Store secrets where a git push cannot reach them
Most credential leaks are not sophisticated. They are a .env file committed by accident, a session file sitting in the project root, a container image that bundled everything in the working directory.
- Add *.session and your environment files to .gitignore on day one, before the first login, not after.
- Keep the bot token and the api_hash in a secrets manager or your platform’s encrypted variables, and inject them at runtime.
- Prefer session strings stored encrypted in a database or secrets store over loose files on disk, and encrypt them with a key that does not live in the same place.
- Never paste tokens or session strings into issue trackers, chat threads or AI assistants while debugging.
- Run a secret scanner (gitleaks, trufflehog or your forge’s built-in scanning) in CI, so a bot token pattern in a commit fails the build.
Separate environments too. A development bot with its own token, a test Telegram account for experiments, and production credentials that only the deployment pipeline can read: if a laptop is lost, the damage stays in the sandbox.
Two-factor authentication and the human side of logins
Every account your application logs into should have a cloud password enabled in Telegram’s Privacy and Security settings, ideally with a recovery email. It does not protect an existing session, but it does stop an attacker who intercepts a login code from creating a new one. This matters because a common takeover scam simply asks the victim to forward the login code Telegram sent them. Telegram warns users never to share these codes, and your own support team should never ask for one either.
If your tooling signs users in by phone number, handle the SESSION_PASSWORD_NEEDED response properly instead of asking people to disable 2FA to make your integration work. Any flow that requires turning off a security feature is a flow to redesign.
Revocation and rotation when something leaks
Write the incident steps down now, while nobody is panicking.
- Bot token leaked: open BotFather, revoke the token, deploy the new one, then check the bot’s webhook settings in case they were changed.
- Session leaked: terminate that session from the Devices or Active Sessions screen in Telegram’s settings, or terminate all other sessions if you cannot tell which one is compromised. Then rotate the 2FA password.
- api_id and api_hash leaked: check what my.telegram.org currently allows for your application, review whether the pair appears in any published code, and audit which sessions were created through it. In practice, the sessions matter more than the pair.
Also watch for the API_ID_PUBLISHED_FLOOD error. Telegram returns it when a published application reuses an api_id that has been exposed in public sample code, a clear signal that every app you ship needs its own credentials.
Make the session list part of your routine
Telegram shows every active session with the application name, platform, approximate location and last activity. For a security-conscious team, that screen is a free audit log. Review it on a schedule for every account your software touches, look for unfamiliar app names or locations, and set the automatic termination period for inactive sessions to something reasonable. If a session you created for a pilot is no longer in use, end it rather than letting it sit there for months.
Reducing what you have to guard in the first place
The strongest control is not holding a secret at all. If your product only needs to let users connect their own Telegram account to a CRM or inbox, consider whether you need to run your own MTProto client and store session material yourself. A unified messaging API such as Unipile connects an existing Telegram user account through Telegram’s own Devices feature, by QR code or Hosted Auth, so you do not manage an api_id, an api_hash or raw session files in your own infrastructure. The connection shows up in the user’s session list like any other device, and if the user terminates it, the account status simply moves to disconnected until they reconnect. Unipile works with user accounts, direct messages and groups, not with bots or channels, and it operates under SOC 2 Type II and GDPR, which gives your security review something concrete to evaluate.
Whichever path you choose, the mindset stays the same: know which strings open which doors, keep them out of your repositories, enforce 2FA, and check the session list as often as you check your server logs.