<p>Authorization is associated with a client's encryption key identifier: <strong>auth_key_id</strong>. No additional parameters need to be passed into methods following authorization. </p>
<p>To log in as a <ahref="/bots">bot</a>, follow <ahref="/api/bots">these instructions »</a>.</p>
<h3><aclass="anchor"href="#sending-a-verification-code"id="sending-a-verification-code"name="sending-a-verification-code"><iclass="anchor-icon"></i></a>Sending a verification code</h3>
<p>To show a nicely formatted and validated phone number field, the <ahref="/constructor/help.countriesList">help.countriesList</a> constructor can be obtained using the <ahref="/method/help.getCountriesList">help.getCountriesList</a> method.<br>
The <ahref="/constructor/help.countriesList">help.countriesList</a> config is then used as described <ahref="/api/config#country-information-and-login-phone-patterns">here »</a>. </p>
<p>Then, a text message containing an authorization code is sent to the user's phone using <ahref="/method/auth.sendCode">auth.sendCode</a>.<br>
However, this is not always the case, if logout tokens are used: </p>
<p>When invoking <ahref="/method/auth.logOut">auth.logOut</a> on a previously authorized session with 2FA enabled, the server may return a <code>future_auth_token</code>, which should be stored in the local database.<br>
When invoking <ahref="/method/auth.sendCode">auth.sendCode</a>, all logout tokens present in the database should be provided to <code>codeSettings.logout_tokens</code>.<br>
If any of the logout tokens matches the account we're trying to login into and the token hasn't expired, <ahref="/method/auth.sendCode">auth.sendCode</a> will directly return a <code>SESSION_PASSWORD_NEEDED</code> RPC error, directly asking the user to <ahref="#2fa">enter the 2FA password</a>, without sending any authorization code. </p>
<p>Otherwise, the system will send an authorization code using the following logic:</p>
<p>The system will automatically choose how to send the authorization code; there are multiple possible ways the code can arrive, signaled to the client via the <ahref="/type/auth.SentCodeType">auth.SentCodeType</a> constructor returned by <ahref="/method/auth.sendCode">auth.sendCode</a>:</p>
<li><ahref="/constructor/auth.sentCodeTypeSetUpEmailRequired">auth.sentCodeTypeSetUpEmailRequired</a>: if the user logins often enough, Telegram will ask the user to verify an email that will be used to send the login code.<br>
See <ahref="#email-verification">here »</a> for more info on the verification process.</li>
<li><ahref="/constructor/auth.sentCodeTypeEmailCode">auth.sentCodeTypeEmailCode</a>: the code was sent to the configured login email.</li>
<li><ahref="/constructor/auth.sentCodeTypeApp">auth.sentCodeTypeApp</a>: the code was sent as a Telegram service notification to all other logged-in sessions.</li>
<li><ahref="/constructor/auth.sentCodeTypeSms">auth.sentCodeTypeSms</a>: the code was sent via SMS.</li>
<li><ahref="/constructor/auth.sentCodeTypeCall">auth.sentCodeTypeCall</a>: the user will receive a phone call and a synthesized voice will tell the user the verification code to input.</li>
<li><ahref="/constructor/auth.sentCodeTypeFlashCall">auth.sentCodeTypeFlashCall</a>: the code will be sent via a flash phone call, that will be closed immediately.<br>
In this case, the phone code will then be the phone number itself, just make sure that the phone number matches the specified pattern (see <ahref="/constructor/auth.sentCodeTypeFlashCall">auth.sentCodeTypeFlashCall</a>).</li>
<li><ahref="/constructor/auth.sentCodeTypeMissedCall">auth.sentCodeTypeMissedCall</a>: the code will be sent via a flash phone call, that will be closed immediately.<br>
The last digits of the phone number that calls are the code that must be entered manually by the user.</li>
<li><ahref="/constructor/auth.loggedOut">Logout tokens »</a>: <ahref="/method/auth.sendCode">auth.sendCode</a> will directly return a <code>SESSION_PASSWORD_NEEDED</code> RPC error, directly asking the user to <ahref="#2fa">enter the 2FA password</a>, without sending any authorization code. </li>
<p>The <ahref="/method/auth.sendCode">auth.sendCode</a> method also has parameters for enabling/disabling use of flash calls and missed 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 <ahref="https://developers.google.com/identity/sms-retriever/overview">android SMS receiver APIs</a>.</p>
<td>Phone code type that will be sent next, if the phone code is not received within <code>timeout</code> seconds: to send it use <ahref="/method/auth.resendCode">auth.resendCode</a></td>
<p>If the message takes too long (<code>timeout</code> seconds) to arrive at the phone, the <ahref="/method/auth.resendCode">auth.resendCode</a> method may be invoked to resend a code of type <code>next_type</code>.
If the same happens again, you can use <ahref="/method/auth.resendCode">auth.resendCode</a> with the <code>next_type</code> returned by the previous call to <ahref="/method/auth.resendCode">auth.resendCode</a>.
To cancel the verification code use <ahref="/method/auth.cancelCode">auth.cancelCode</a>.</p>
<p>Telegram may return a <ahref="/constructor/auth.sentCodeTypeSetUpEmailRequired">auth.sentCodeTypeSetUpEmailRequired</a> code type in the <ahref="/constructor/auth.sentCode">auth.sentCode</a> constructor returned by <ahref="/method/auth.sendCode">auth.sendCode</a>.<br>
In this case, clients should ask the user to verify an email address that will be used to receive the login code as follows: </p>
<ul>
<li>
<p>If the <code>google_signin_allowed</code> or <code>apple_signin_allowed</code> flags are set, users can directly verify their email with Google/Apple ID as specified <ahref="https://developers.google.com/identity/sign-in/android/sign-in">here (Google ID) »</a> and <ahref="https://developer.apple.com/documentation/sign_in_with_apple">here (Apple ID) »</a>.<br>
After obtaining the ID token, call <ahref="/method/account.verifyEmail">account.verifyEmail</a>, providing the following parameters:</p>
<ul>
<li><code>purpose</code> - A <ahref="/constructor/emailVerifyPurposeLoginSetup">emailVerifyPurposeLoginSetup</a> constructor</li>
<li><code>purpose.phone_number</code> - The phone number used with <ahref="/method/auth.sendCode">auth.sendCode</a></li>
<li><code>purpose.phone_code_hash</code> - The phone code hash contained in the <ahref="/constructor/auth.sentCode">auth.sentCode</a> constructor returned by <ahref="/method/auth.sendCode">auth.sendCode</a></li>
<li><code>verification</code> - <ahref="/constructor/emailVerificationGoogle">emailVerificationGoogle</a> or <ahref="/constructor/emailVerificationApple">emailVerificationApple</a></li>
<li><code>verification.token</code> - The ID token returned by the Google ID API.</li>
</ul>
<p>On success, the <ahref="/method/account.verifyEmail">account.verifyEmail</a> method will return a <ahref="/constructor/account.emailVerifiedLogin">account.emailVerifiedLogin</a> constructor with an <ahref="/constructor/auth.sentCode">auth.sentCode</a> constructor that should be handled <ahref="#code-types">as usual »</a>. </p>
</li>
<li>
<p>Otherwise, ask the user to enter an email address and then call <ahref="/method/account.sendVerifyEmailCode">account.sendVerifyEmailCode</a>, providing the following parameters:</p>
<ul>
<li><code>email</code> - The email address</li>
<li><code>purpose</code> - A <ahref="/constructor/emailVerifyPurposeLoginSetup">emailVerifyPurposeLoginSetup</a> constructor</li>
<li><code>purpose.phone_number</code> - The phone number used with <ahref="/method/auth.sendCode">auth.sendCode</a></li>
<li><code>purpose.phone_code_hash</code> - The phone code hash contained in the <ahref="/constructor/auth.sentCode">auth.sentCode</a> constructor returned by <ahref="/method/auth.sendCode">auth.sendCode</a></li>
</ul>
<p>Once the user receives and inputs the verification code, call <ahref="/method/account.verifyEmail">account.verifyEmail</a>, providing the following parameters:</p>
<ul>
<li><code>purpose</code> - A <ahref="/constructor/emailVerifyPurposeLoginSetup">emailVerifyPurposeLoginSetup</a> constructor</li>
<li><code>purpose.phone_number</code> - The phone number used with <ahref="/method/auth.sendCode">auth.sendCode</a></li>
<li><code>purpose.phone_code_hash</code> - The phone code hash contained in the <ahref="/constructor/auth.sentCode">auth.sentCode</a> constructor returned by <ahref="/method/auth.sendCode">auth.sendCode</a></li>
<li><code>verification.code</code> - The verification code received by the user.</li>
</ul>
<p>On success, the <ahref="/method/account.verifyEmail">account.verifyEmail</a> method will return a <ahref="/constructor/account.emailVerifiedLogin">account.emailVerifiedLogin</a> constructor with an <ahref="/constructor/auth.sentCode">auth.sentCode</a> constructor that should be handled <ahref="#code-types">as usual »</a>. </p>
</li>
</ul>
<p>To change the login email after login, pass <ahref="/constructor/emailVerifyPurposeLoginChange">emailVerifyPurposeLoginChange</a> as <code>purpose</code>, following the exact same Google ID/Apple ID/email code login flow as above: on success, the <ahref="/method/account.verifyEmail">account.verifyEmail</a> method will return an <ahref="/constructor/account.emailVerified">account.emailVerified</a> constructor.</p>
<p>When user enters verification code, the <ahref="/method/auth.signIn">auth.signIn</a> method must be used to validate it and possibly sign user in.</p>
<p>If the code was entered correctly, but the method returns <ahref="/constructor/auth.authorizationSignUpRequired">auth.authorizationSignUpRequired</a>, 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 (<ahref="/method/auth.signUp">auth.signUp</a>) must be invoked.</p>
<p>When trying to sign in using <ahref="/method/auth.signIn">auth.signIn</a>, an <ahref="/method/auth.signIn#possible-errors">error 400 SESSION_PASSWORD_NEEDED</a> may be returned, if the user has two-factor authentication enabled.
In this case, instructions for <ahref="/api/srp">SRP 2FA authentication</a> must be followed.</p>
<p>Each phone number is limited to only a certain amount of logins per day (e.g. 5, but this is subject to change) after which the API will return a FLOOD error until the next day. This might not be enough for testing the implementation of User Authorization flows in client applications.</p>
<p>There are several reserved phone number prefixes for testing that your application handles redirects between DCs, sign up, sign in and 2FA flows correctly. These numbers are only available on <strong>Test DCs</strong> (their IP addresses for TCP transport are available in <ahref="https://my.telegram.org/apps">API development tools</a> panel after <ahref="https://core.telegram.org/api/obtaining_api_id#obtaining-api-id">api_id was obtained</a>, <ahref="https://core.telegram.org/mtproto/transports#uri-format">URI format</a> for HTTPS/Websocket transport).</p>
<p>If you wish to emulate an application of a user associated with DC number X, it is sufficient to specify the phone number as <code>99966XYYYY</code>, where YYYY are random numbers, when registering the user. A user like this would always get XXXXX as the login confirmation code (the DC number, repeated five times). Note that the value of X must be in the range of 1-3 because there are only 3 Test DCs. When the flood limit is reached for any particular test number, just choose another number (changing the YYYY random part).</p>
<p>Do not store any important or private information in the messages of such test accounts; anyone can make use of the simplified authorization mechanism – and we periodically wipe all information stored there.</p>
<p>Proceed with User Authorization flows in <strong>Production DCs</strong> only after you make sure everything works correctly on <strong>Test DCs</strong> first to avoid reaching flood limits.</p>
<blockquote>
<p>To help you with working on production DCs, logins with the same phone number with which the <code>api_id</code> was registered have more generous flood limits.</p>
<h3><aclass="anchor"href="#we-are-authorized"id="we-are-authorized"name="we-are-authorized"><iclass="anchor-icon"></i></a>We are authorized</h3>
<p>As a result of authorization, the client key, <strong>auth_key_id</strong>, 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.</p>
