The short answer
- 1Telegram login is now standard OpenID Connect with PKCE, set up through a bot in @BotFather.
- 2Register allowed URLs, take the Client ID and Secret, and keep the Secret on your server.
- 3Exchange the code server-side and verify the ID token's signature before trusting it.
In this article
What "Log in with Telegram" is now
A "Log in with Telegram" button lets visitors sign in to your site or app with their Telegram account instead of creating a new password. Telegram now documents this as an OpenID Connect flow, the same standard used by other "sign in with" buttons: the authorization code flow, with PKCE. The older iframe JavaScript widget's documentation has been moved to an archive page.
| Item | Detail |
|---|---|
| You need | A bot to represent your service, created with @BotFather |
| You get | A Client ID and a Client Secret, from the bot's Login Widget settings |
| You register | The allowed URLs: your site's origins and the redirect URIs users return to |
| Ways to add it | The official web library, official iOS and Android SDKs, or standard OpenID Connect by hand |
Setting it up
- Create or pick a bot in @BotFather; see creating a bot with BotFather. Its name and photo appear on the login prompt as if they were your service's, so make them recognisable.
- Register your allowed URLs in the bot's Login Widget settings. Login does not open from addresses you have not registered.
- Copy the Client ID and Client Secret shown there.
- Add the button with the official library, or follow the flow below if you implement it yourself.
The flow, if you implement it yourself
- Send the user to Telegram. The browser goes to oauth.telegram.org with your client ID, redirect URI, the scopes you want, a state value against forged requests and a PKCE challenge.
- They come back with a code. If the user agrees, Telegram redirects to your URI with a one-time code.
- Exchange it on your server. Your server sends the code, the PKCE verifier and your client credentials to the token endpoint and receives an ID token and an access token. This step must happen server-side.
- Verify before you trust. Check the ID token's signature against Telegram's published keys (JWKS), and that the issuer is Telegram, the audience is your bot, and it has not expired. Only then use what it says about the user.
Telegram has no separate UserInfo endpoint, so some OpenID Connect libraries need to be told not to ask for one; the user data comes in the ID token.
What you can ask for
| Scope | What it gives you |
|---|---|
| openid | Required. A stable identifier for the user |
| profile | Basic details such as name, username and photo |
| phone | The verified phone number, only if the user agrees |
| telegram:bot_access | Permission for your bot to send the user direct messages |
Ask only for what you use. Users can refuse the phone number and the bot permission, so sign-in should still work without them. The last scope is the one way a user lets your bot message them first, which bots otherwise cannot do; see bot accounts vs user-account automation.
FAQ
How does Log In With Telegram work for websites now?
It uses OpenID Connect. You register a bot in @BotFather, send users to oauth.telegram.org, exchange the returned code on your server and verify the ID token.
Where do I get the Telegram login Client ID and Secret?
In @BotFather, in your bot's Login Widget settings, after registering your allowed URLs.
Can my bot message users who logged in with Telegram?
Only if they grant the telegram:bot_access scope during login.
Sources
At a glance
- 1Setup
Bot's Login Widget: URLs, Client ID, Secret.
- 2Flow
Redirect, code, server exchange, verify ID token.
- 3Scopes
openid, profile, phone, telegram:bot_access.
Updated
