User Authorization

Authorization is associated with a client’s encryption key identifier: auth_key_id. No additional parameters need to be passed into methods following authorization.

Sending a verification code

Example implementations: telegram for android, tdlib.

Authorization requires that a text message containing an authorization code first be sent to the user’s phone.
This may be done using the auth.sendCode method.
The system will automatically choose how to send the authorization code; there are four possible ways the code can arrive:

  • Telegram code
  • SMS code
  • Phone call: a synthesized voice will tell the user which verification code to input
  • Flash phone call: the code will be sent via a flash phone call, that will be closed immediately.
    In the last case, the phone code will then be the phone number itself, just make sure that the phone number matches the specified pattern (see auth.sentCodeTypeFlashCall).

The auth.sendCode method also has parameters for enabling/disabling use of flash calls, and allows passing an SMS token that will be included in the sent SMS.
For example, the latter is required in newer versions of android, to use the android SMS receiver APIs.

The returned auth.SentCode object will contain multiple parameters:

flags # Flags, see TL conditional fields
type auth.SentCodeType Phone code type
phone_code_hash string Phone code hash, to be stored and later re-used with auth.signIn
next_type flags.1?auth.CodeType Phone code type that will be sent next, if the phone code is not received within timeout seconds: to send it use auth.resendCode
timeout flags.2?int Timeout for reception of the phone code

If the message takes too long (timeout seconds) to arrive at the phone, the auth.resendCode method may be invoked to resend a code of type next_type.
If the same happens again, you can use auth.resendCode with the next_type returned by the previous call to auth.resendCode.
To cancel the verification code use auth.cancelCode.

Sign in/sign up

When user enters verification code, the auth.signIn method must be used to validate it and possibly sign user in.

If the code was entered correctly, but the method returns auth.authorizationSignUpRequired, it means that account with this phone number doesn't exist yet: user needs to provide basic information, accept terms of service and then the new user registration method (auth.signUp) must be invoked.

2FA

When trying to sign in using auth.signIn, an error 400 SESSION_PASSWORD_NEEDED may be returned, if the user has two-factor authentication enabled.
In this case, instructions for SRP 2FA authentication must be followed.

To set up two-factor authorization on an already authorized account, follow the SRP 2FA authentication docs.

Test Phone Numbers

One phone number is limited to only certain amounts of logins per day (e.g. 5, but subject to change), after that API will return one of FLOOD errors until the next date. This might be not enough for testing while implementing and testing User Authorization flows in client application.

To resolve this problem there are reserved phone number prefixes to test the correctness of the application’s handling redirects between DCs, sign up, sign in and 2FA flows. These numbers are only available on Test DCs (their IP addresses for TCP transport are availble in API development tools panel after api_id was obtained, URI format for HTTPS/Websocket transport).

If you wish to emulate an application of a user associated with DC number X, it is sufficient to specify the phone number as 99966XYYYY, where YYYY are random numbers, when registering the user. A user like this would always get XXXXX as the confirmation code (the DC number, repeated five times). Note that there are only Test DCs 1-3 and Production DCs 1-5, X value should be in that range. When flood limit is reached for any particular test number, just choose another one (changing YYYY random part).

Do not store any important or private information in such test users’ messages; anyone can make use of the simplified authorization mechanism.

Proceed with User Authorization flows in Production DCs only after you make sure everything works correctly on Test DCs first to avoid reaching flood limits.

Logins with the same phone number, the api_id was registered with, have more generous limits.

We are authorized

As a result of authorization, the client key, auth_key_id, becomes associated with the user, and each subsequent API call with this key will be executed with that user’s identity. The authorization method itself returns the relevant user. It is best to immediately store the User ID locally in a binding with the key.

Only a small portion of the API methods are available to unauthorized users:

Other methods will result in an error: 401 UNAUTHORIZED.