The short answer
- 1auth.sendCode, then auth.signIn (or signUp for a new number), then SRP if 2FA is on.
- 2The server chooses how the code is delivered; show matching instructions.
- 3Develop against the test server and test numbers to avoid rate limits.
In this article
Three steps, and one more
Logging a user account in through the Telegram API is the same thing the official apps do. With TDLib the library reports each stage to you as an authorization state; if you work with MTProto directly, you call these methods in order.
| Step | Method | What it does |
|---|---|---|
| 1. Request a code | auth.sendCode | Sends the phone number with your api_id and api_hash. The server replies with how the code was sent and a phone_code_hash |
| 2. Enter the code | auth.signIn | Logs in with the code and the phone_code_hash |
| 2a. New number | auth.signUp | If the reply says sign-up is needed, collect a name and register, including acceptance of the terms of service |
| 3. Two-Step Verification | account.getPassword → auth.checkPassword | If SESSION_PASSWORD_NEEDED comes back, prove the password with SRP |
How to get an api_id and api_hash is in getting an api_id safely, and choosing between the APIs in the four Telegram APIs.
The code can arrive several ways
The server decides where to send the code and tells you which way in its reply. Show instructions that match, or users get lost.
| Delivery | What to tell the user |
|---|---|
| App | Look for the official Telegram notification on another device that is already logged in |
| SMS or call | Wait for a text message or an automated voice call |
| Missed call | The last digits of the incoming number are the code |
| Check the login email address for the code | |
| Fragment | Anonymous +888 numbers receive their code on fragment.com |
auth.resendCode asks for the code another way and auth.cancelCode gives up. When the server tells you the next method and how long to wait, do not ask again before then. There is also account.invalidateSignInCodes, which cancels codes when there are signs a user passed one on to someone else.
Use the test server and test numbers while developing
Requesting a real code every time you fix your login flow piles up requests and can get you rate-limited. The official documentation describes test numbers for the test data centers: they start with 99966, followed by the data center number and four random digits, and their login code is the data center number repeated five times. The test server's address is on your app's page at my.telegram.org.
Two-Step Verification: the password is never sent
For an account with Two-Step Verification, the cloud password is asked after the code. The password itself never goes to the server. You take the salts and parameters from account.getPassword, compute a value that proves you know the password, and send that to auth.checkPassword. This is the SRP method. It is long and easy to get wrong, so a library such as TDLib is the better choice; see building TDLib.
After login: sessions and logging out
The new session appears in the user's Devices list under your app's name. Tell users they can end it from there. When a session is ended, the next request fails with a 401 error such as AUTH_KEY_UNREGISTERED or SESSION_REVOKED; send the user back to the login screen. See reading API errors. To log out, call auth.logOut and delete the session file left on the device.
FAQ
What is phone_code_hash?
A value auth.sendCode returns that you must pass back to auth.signIn together with the code.
What does SESSION_PASSWORD_NEEDED mean?
The account has Two-Step Verification. Call account.getPassword and prove the password with SRP via auth.checkPassword.
How do I test login without real phone numbers?
Use the test data centers and their test numbers starting with 99966; the code is the data center number repeated five times.
Sources
At a glance
- 1Flow
sendCode → signIn/signUp → getPassword → checkPassword.
- 2Delivery
App, SMS, call, missed call, email or Fragment.
- 32FA
SRP proves the password without sending it; use TDLib.
Updated
