telegram-crawler/data/web/core.telegram.org/api/auth.html

336 lines
31 KiB
HTML
Raw Normal View History

2022-02-24 19:51:11 +01:00
<!DOCTYPE html>
<html class="">
<head>
<meta charset="utf-8">
<title>User Authorization</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta property="description" content="How to register a user&#39;s phone to start using the API.">
<meta property="og:title" content="User Authorization">
<meta property="og:image" content="9ebfef6d534b708d3a">
<meta property="og:description" content="How to register a user&#39;s phone to start using the API.">
2022-04-21 15:52:36 +02:00
<link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4">
<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png">
<link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" />
2022-02-24 19:51:11 +01:00
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
2024-08-02 02:44:36 +02:00
<link href="/css/telegram.css?240" rel="stylesheet" media="screen">
2022-02-24 19:51:11 +01:00
<style>
</style>
</head>
<body class="preload">
<div class="dev_page_wrap">
<div class="dev_page_head navbar navbar-static-top navbar-tg">
<div class="navbar-inner">
<div class="container clearfix">
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
<ul class="nav navbar-nav">
<li><a href="//telegram.org/">Home</a></li>
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
<li class="active"><a href="/api">API</a></li>
<li class=""><a href="/mtproto">Protocol</a></li>
<li class=""><a href="/schema">Schema</a></li>
</ul>
</div>
</div>
</div>
<div class="container clearfix">
<div class="dev_page">
<div id="dev_page_content_wrap" class=" ">
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/api" >API</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/api/auth" >User Authorization</a></li></ul></div>
<h1 id="dev_page_title">User Authorization</h1>
<div id="dev_page_content"><!-- scroll_nav -->
2024-05-06 15:31:53 +02:00
<p>Authorization is associated with a client&#39;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 <a href="/bots">bot</a>, follow <a href="/api/bots">these instructions &raquo;</a>.</p>
<p>An alternative <a href="/api/qr-login">QR code-based login flow is also available &raquo;</a>.</p>
<h3><a class="anchor" name="sending-a-verification-code" href="#sending-a-verification-code"><i class="anchor-icon"></i></a>Sending a verification code</h3>
2022-02-24 19:51:11 +01:00
<p>Example implementations: <a href="https://github.com/DrKLO/Telegram/blob/master/TMessagesProj/src/main/java/org/telegram/ui/LoginActivity.java">telegram for android</a>, <a href="https://github.com/tdlib/td/tree/master/td/telegram/SendCodeHelper.cpp">tdlib</a>.</p>
2024-05-06 15:31:53 +02:00
<p>To show a nicely formatted and validated phone number field, the <a href="/constructor/help.countriesList">help.countriesList</a> constructor can be obtained using the <a href="/method/help.getCountriesList">help.getCountriesList</a> method.<br>The <a href="/constructor/help.countriesList">help.countriesList</a> config and other configuration values are then used as described <a href="/api/config#country-information-and-login-phone-patterns">here &raquo;</a>. </p>
<p>Then, a text message containing an authorization code is sent to the user&#39;s phone using <a href="/method/auth.sendCode">auth.sendCode</a>.<br>However, this is not always the case, if future auth tokens are used: </p>
<h4><a class="anchor" name="future-auth-tokens" href="#future-auth-tokens"><i class="anchor-icon"></i></a>Future auth tokens</h4>
<p>When invoking <a href="/method/auth.logOut">auth.logOut</a> on a previously authorized session, the server may return a <code>future_auth_token</code>, which should be stored in the local database.<br>A <code>future_auth_token</code> is also contained in the <a href="/constructor/auth.authorization">auth.authorization</a> returned when logging in.<br>At all times, the future auth token database should contain at most 20 tokens: evict older tokens as new tokens are added to stay below this limit.<br>When invoking <a href="/method/auth.sendCode">auth.sendCode</a>, all future auth tokens present in the database should be provided to <code>codeSettings.logout_tokens</code>.<br>If any of the future auth tokens matches the account we&#39;re trying to login into and the token hasn&#39;t expired:</p>
2023-05-22 14:54:47 +02:00
<ul>
<li>If <a href="/api/srp">2FA</a> is not enabled, <a href="/method/auth.sendCode">auth.sendCode</a> will is directly return an <a href="/constructor/auth.sentCodeSuccess">auth.sentCodeSuccess</a> constructor with session info, indicating the session is authorized.</li>
<li>If <a href="/api/srp">2FA</a> is enabled, <a href="/method/auth.sendCode">auth.sendCode</a> will return a <code>SESSION_PASSWORD_NEEDED</code> RPC error, asking the user to <a href="#2fa">enter the 2FA password</a>, without sending any authorization code. </li>
</ul>
2022-03-10 21:15:11 +01:00
<p>Otherwise, the system will send an authorization code using the following logic:</p>
2024-05-06 15:31:53 +02:00
<h4><a class="anchor" name="code-types" href="#code-types"><i class="anchor-icon"></i></a>Code types</h4>
<pre><code>codeSettings#ad253d78 flags:# allow_flashcall:flags.0?true current_number:flags.1?true allow_app_hash:flags.4?true allow_missed_call:flags.5?true allow_firebase:flags.7?true logout_tokens:flags.6?Vector&lt;bytes&gt; token:flags.8?string app_sandbox:flags.8?Bool = CodeSettings;
2023-05-22 14:54:47 +02:00
2024-05-06 15:31:53 +02:00
auth.sentCodeTypeApp#3dbb5986 length:int = auth.SentCodeType;
auth.sentCodeTypeSms#c000bba2 length:int = auth.SentCodeType;
auth.sentCodeTypeCall#5353e5a7 length:int = auth.SentCodeType;
auth.sentCodeTypeFlashCall#ab03c6d9 pattern:string = auth.SentCodeType;
auth.sentCodeTypeMissedCall#82006484 prefix:string length:int = auth.SentCodeType;
auth.sentCodeTypeEmailCode#f450f59b flags:# apple_signin_allowed:flags.0?true google_signin_allowed:flags.1?true email_pattern:string length:int reset_available_period:flags.3?int reset_pending_date:flags.4?int = auth.SentCodeType;
auth.sentCodeTypeSetUpEmailRequired#a5491dea flags:# apple_signin_allowed:flags.0?true google_signin_allowed:flags.1?true = auth.SentCodeType;
auth.sentCodeTypeFragmentSms#d9565c39 url:string length:int = auth.SentCodeType;
auth.sentCodeTypeFirebaseSms#e57b1432 flags:# nonce:flags.0?bytes receipt:flags.1?string push_timeout:flags.1?int length:int = auth.SentCodeType;
2023-05-22 14:54:47 +02:00
2024-05-06 15:31:53 +02:00
auth.sentCode#5e002502 flags:# type:auth.SentCodeType phone_code_hash:string next_type:flags.1?auth.CodeType timeout:flags.2?int = auth.SentCode;
auth.sentCodeSuccess#2390fe44 authorization:auth.Authorization = auth.SentCode;
2023-05-22 14:54:47 +02:00
---functions---
2024-05-06 15:31:53 +02:00
auth.sendCode#a677244f phone_number:string api_id:int api_hash:string settings:CodeSettings = auth.SentCode;
auth.resendCode#3ef1a9bf phone_number:string phone_code_hash:string = auth.SentCode;
2023-05-22 14:54:47 +02:00
2024-05-06 15:31:53 +02:00
auth.requestFirebaseSms#89464b50 flags:# phone_number:string phone_code_hash:string safety_net_token:flags.0?string ios_push_secret:flags.1?string = Bool;</code></pre>
<p>The <a href="/method/auth.sendCode">auth.sendCode</a> method 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.<br>For example, the latter is required in newer versions of android, to use the <a href="https://developers.google.com/identity/sms-retriever/overview">android SMS receiver APIs</a>.</p>
2023-05-22 14:54:47 +02:00
<p>The returned <a href="/constructor/auth.sentCode">auth.sentCode</a> object will contain multiple parameters:</p>
2022-02-24 19:51:11 +01:00
<table class="table">
<tbody>
<tr>
<td><strong>flags</strong></td>
2024-05-06 15:31:53 +02:00
<td align="center"><a href="/type/%23">#</a></td>
2022-02-24 19:51:11 +01:00
<td>Flags, see <a href="/mtproto/TL-combinators#conditional-fields">TL conditional fields</a></td>
</tr>
<tr>
<td><strong>type</strong></td>
2024-05-06 15:31:53 +02:00
<td align="center"><a href="/type/auth.SentCodeType">auth.SentCodeType</a></td>
2022-02-24 19:51:11 +01:00
<td>Phone code type</td>
</tr>
<tr>
<td><strong>phone_code_hash</strong></td>
2024-05-06 15:31:53 +02:00
<td align="center"><a href="/type/string">string</a></td>
2023-05-22 14:54:47 +02:00
<td>Phone code hash, to be stored and re-used in later method calls</td>
2022-02-24 19:51:11 +01:00
</tr>
<tr>
<td><strong>next_type</strong></td>
2024-05-06 15:31:53 +02:00
<td align="center"><a href="/mtproto/TL-combinators#conditional-fields">flags</a>.1?<a href="/type/auth.CodeType">auth.CodeType</a></td>
2022-02-24 19:51:11 +01:00
<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 <a href="/method/auth.resendCode">auth.resendCode</a></td>
</tr>
<tr>
<td><strong>timeout</strong></td>
2024-05-06 15:31:53 +02:00
<td align="center"><a href="/mtproto/TL-combinators#conditional-fields">flags</a>.2?<a href="/type/int">int</a></td>
2022-02-24 19:51:11 +01:00
<td>Timeout for reception of the phone code</td>
</tr>
</tbody>
</table>
2023-05-22 14:54:47 +02:00
<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 <code>type</code> field of the <a href="/type/auth.SentCodeType">auth.SentCodeType</a> constructor. </p>
2024-05-06 15:31:53 +02:00
<p>Note that in some conditions when signing up or logging in using an SMS code/call, only the <a href="/constructor/auth.sentCodeTypeFirebaseSms">auth.sentCodeTypeFirebaseSms</a> code type may be used.<br>Currently, only official apps can make use of Firebase SMS authentication: this means that in some conditions, only the official applications can receive a login/signup code via SMS/call.<br>Third-party apps may log in using any of the other code delivery methods (Telegram codes, Fragment codes, email codes, future auth tokens, <a href="/api/qr-login">QR codes</a>).</p>
2023-05-22 14:54:47 +02:00
<ul>
2024-05-06 15:31:53 +02:00
<li><a href="/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 <a href="#email-verification">here &raquo;</a> for more info on the verification process.</li>
2023-05-22 14:54:47 +02:00
<li><a href="/constructor/auth.sentCodeTypeEmailCode">auth.sentCodeTypeEmailCode</a>: the code was sent to the configured login email.</li>
<li><a href="/constructor/auth.sentCodeTypeFragmentSms">auth.sentCodeTypeFragmentSms</a>: the code was sent via <a href="https://fragment.com">fragment.com</a>: open the specified <code>url</code> to log into the <a href="https://fragment.com">Fragment</a> platform with your wallet and view the code. </li>
<li><a href="/constructor/auth.sentCodeTypeApp">auth.sentCodeTypeApp</a>: the code was sent as a Telegram service notification to all other logged-in sessions.</li>
<li><a href="/constructor/auth.sentCodeTypeFirebaseSms">auth.sentCodeTypeFirebaseSms</a>: firebase login flow, only for official apps. <ul>
2024-05-06 15:31:53 +02:00
<li>On Android, can only be received if the <a href="/constructor/codeSettings">codeSettings</a>.<code>allow_firebase</code> flag is set.<br>The client must pass the received <a href="/constructor/auth.sentCodeTypeFirebaseSms">auth.sentCodeTypeFirebaseSms</a>.<code>nonce</code> to the <a href="https://developer.android.com/training/safetynet/attestation">SafetyNet Attestation API</a>, and then pass the obtained JWS object to <a href="/method/auth.requestFirebaseSms">auth.requestFirebaseSms</a>.<code>safety_net_token</code>, along with the <code>phone_number</code> and the <code>phone_code_hash</code>.<br>If the method returns <a href="/constructor/boolTrue">boolTrue</a>, the code will be sent via SMS; otherwise, the <code>next_type</code> authentication method must be used, with <a href="/method/auth.resendCode">auth.resendCode</a>.</li>
<li>On iOS, can only be received if the device token for Apple Push was passed to <a href="/constructor/codeSettings">codeSettings</a>.<code>token</code>.<br>The client then waits for a new push notification for <a href="/constructor/auth.sentCodeTypeFirebaseSms">auth.sentCodeTypeFirebaseSms</a>.<code>push_timeout</code> seconds.<br>If a push notification isn&#39;t received within <code>push_timeout</code> seconds, the <code>next_type</code> authentication method must be used, with <a href="/method/auth.resendCode">auth.resendCode</a>.<br>If a push notification is received with <code>receipt</code> and <code>ios_push_secret</code> fields, and the value of the <code>receipt</code> field matches <a href="/constructor/codeSettings">codeSettings</a>.<code>receipt</code>, the value of <code>ios_push_secret</code> is passed to <a href="/method/auth.requestFirebaseSms">auth.requestFirebaseSms</a>.<code>ios_push_secret</code>, along with the <code>phone_number</code> and the <code>phone_code_hash</code>.<br>If the method returns <a href="/constructor/boolTrue">boolTrue</a>, the code will be sent via SMS; otherwise, the <code>next_type</code> authentication method must be used, with <a href="/method/auth.resendCode">auth.resendCode</a>.</li>
2023-05-22 14:54:47 +02:00
</ul>
</li>
<li><a href="/constructor/auth.sentCodeTypeSms">auth.sentCodeTypeSms</a>: the code was sent via SMS.</li>
<li><a href="/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>
2024-05-06 15:31:53 +02:00
<li><a href="/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 <a href="/constructor/auth.sentCodeTypeFlashCall">auth.sentCodeTypeFlashCall</a>).</li>
<li><a href="/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><a href="#future-auth-tokens">Future auth tokens &raquo;</a></li>
2023-05-22 14:54:47 +02:00
</ul>
2024-05-06 15:31:53 +02:00
<p>If the message takes too long (<code>timeout</code> seconds) to arrive at the phone, the <a href="/method/auth.resendCode">auth.resendCode</a> method may be invoked to resend a code of type <code>next_type</code>.<br>If the same happens again, you can use <a href="/method/auth.resendCode">auth.resendCode</a> with the <code>next_type</code> returned by the previous call to <a href="/method/auth.resendCode">auth.resendCode</a>.<br>To cancel the verification code use <a href="/method/auth.cancelCode">auth.cancelCode</a>.</p>
<h3><a class="anchor" name="email-verification" href="#email-verification"><i class="anchor-icon"></i></a>Email verification</h3>
<pre><code>auth.sentCodeTypeSetUpEmailRequired#a5491dea flags:# apple_signin_allowed:flags.0?true google_signin_allowed:flags.1?true = auth.SentCodeType;
2022-11-15 00:55:37 +01:00
2024-05-06 15:31:53 +02:00
emailVerifyPurposeLoginSetup#4345be73 phone_number:string phone_code_hash:string = EmailVerifyPurpose;
2022-11-15 00:55:37 +01:00
2024-05-06 15:31:53 +02:00
emailVerificationCode#922e55a9 code:string = EmailVerification;
emailVerificationGoogle#db909ec2 token:string = EmailVerification;
emailVerificationApple#96d074fd token:string = EmailVerification;
2022-11-15 00:55:37 +01:00
2024-05-06 15:31:53 +02:00
account.sentEmailCode#811f854f email_pattern:string length:int = account.SentEmailCode;
2022-11-15 00:55:37 +01:00
2024-05-06 15:31:53 +02:00
account.emailVerifiedLogin#e1bb0d61 email:string sent_code:auth.SentCode = account.EmailVerified;
2022-11-15 00:55:37 +01:00
2024-05-06 15:31:53 +02:00
emailVerifyPurposeLoginChange#527d22eb = EmailVerifyPurpose;
account.emailVerified#2b96cd1b email:string = account.EmailVerified;
2022-11-15 00:55:37 +01:00
---functions---
2024-05-06 15:31:53 +02:00
account.sendVerifyEmailCode#98e037bb purpose:EmailVerifyPurpose email:string = account.SentEmailCode;
account.verifyEmail#32da4cf purpose:EmailVerifyPurpose verification:EmailVerification = account.EmailVerified;
auth.resetLoginEmail#7e960193 phone_number:string phone_code_hash:string = auth.SentCode;</code></pre>
<p>Telegram may return a <a href="/constructor/auth.sentCodeTypeSetUpEmailRequired">auth.sentCodeTypeSetUpEmailRequired</a> code type in the <a href="/constructor/auth.sentCode">auth.sentCode</a> constructor returned by <a href="/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>
2022-11-15 00:55:37 +01:00
<ul>
2024-05-06 15:31:53 +02:00
<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 <a href="https://developers.google.com/identity/sign-in/android/sign-in">here (Google ID) &raquo;</a> and <a href="https://developer.apple.com/documentation/sign_in_with_apple">here (Apple ID) &raquo;</a>.<br>After obtaining the ID token, call <a href="/method/account.verifyEmail">account.verifyEmail</a>, providing the following parameters:</p>
2022-11-15 00:55:37 +01:00
<ul>
<li><code>purpose</code> - A <a href="/constructor/emailVerifyPurposeLoginSetup">emailVerifyPurposeLoginSetup</a> constructor</li>
<li><code>purpose.phone_number</code> - The phone number used with <a href="/method/auth.sendCode">auth.sendCode</a></li>
<li><code>purpose.phone_code_hash</code> - The phone code hash contained in the <a href="/constructor/auth.sentCode">auth.sentCode</a> constructor returned by <a href="/method/auth.sendCode">auth.sendCode</a></li>
<li><code>verification</code> - <a href="/constructor/emailVerificationGoogle">emailVerificationGoogle</a> or <a href="/constructor/emailVerificationApple">emailVerificationApple</a></li>
<li><code>verification.token</code> - The ID token returned by the Google ID API.</li>
</ul>
2024-05-06 15:31:53 +02:00
<p>On success, the <a href="/method/account.verifyEmail">account.verifyEmail</a> method will return a <a href="/constructor/account.emailVerifiedLogin">account.emailVerifiedLogin</a> constructor with an <a href="/constructor/auth.sentCode">auth.sentCode</a> constructor that should be handled <a href="#code-types">as usual &raquo;</a>. </p>
2022-11-15 00:55:37 +01:00
</li>
2024-05-06 15:31:53 +02:00
<li><p>Otherwise, ask the user to enter an email address and then call <a href="/method/account.sendVerifyEmailCode">account.sendVerifyEmailCode</a>, providing the following parameters:</p>
2022-11-15 00:55:37 +01:00
<ul>
<li><code>email</code> - The email address</li>
<li><code>purpose</code> - A <a href="/constructor/emailVerifyPurposeLoginSetup">emailVerifyPurposeLoginSetup</a> constructor</li>
<li><code>purpose.phone_number</code> - The phone number used with <a href="/method/auth.sendCode">auth.sendCode</a></li>
<li><code>purpose.phone_code_hash</code> - The phone code hash contained in the <a href="/constructor/auth.sentCode">auth.sentCode</a> constructor returned by <a href="/method/auth.sendCode">auth.sendCode</a></li>
</ul>
<p>Once the user receives and inputs the verification code, call <a href="/method/account.verifyEmail">account.verifyEmail</a>, providing the following parameters:</p>
<ul>
<li><code>purpose</code> - A <a href="/constructor/emailVerifyPurposeLoginSetup">emailVerifyPurposeLoginSetup</a> constructor</li>
<li><code>purpose.phone_number</code> - The phone number used with <a href="/method/auth.sendCode">auth.sendCode</a></li>
<li><code>purpose.phone_code_hash</code> - The phone code hash contained in the <a href="/constructor/auth.sentCode">auth.sentCode</a> constructor returned by <a href="/method/auth.sendCode">auth.sendCode</a></li>
<li><code>verification</code> - <a href="/constructor/emailVerificationCode">emailVerificationCode</a></li>
<li><code>verification.code</code> - The verification code received by the user.</li>
</ul>
2024-05-06 15:31:53 +02:00
<p>On success, the <a href="/method/account.verifyEmail">account.verifyEmail</a> method will return a <a href="/constructor/account.emailVerifiedLogin">account.emailVerifiedLogin</a> constructor with an <a href="/constructor/auth.sentCode">auth.sentCode</a> constructor that should be handled <a href="#code-types">as usual &raquo;</a>. </p>
2022-11-15 00:55:37 +01:00
</li>
</ul>
2023-05-22 14:54:47 +02:00
<p>If the user cannot access their email address, an email reset may be requested using <a href="/method/auth.resetLoginEmail">auth.resetLoginEmail</a>. </p>
2022-11-15 00:55:37 +01:00
<p>To change the login email after login, pass <a href="/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 <a href="/method/account.verifyEmail">account.verifyEmail</a> method will return an <a href="/constructor/account.emailVerified">account.emailVerified</a> constructor.</p>
2024-05-06 15:31:53 +02:00
<h3><a class="anchor" name="sign-in-sign-up" href="#sign-in-sign-up"><i class="anchor-icon"></i></a>Sign in/sign up</h3>
2022-02-24 19:51:11 +01:00
<p>When user enters verification code, the <a href="/method/auth.signIn">auth.signIn</a> method must be used to validate it and possibly sign user in.</p>
2024-05-06 15:31:53 +02:00
<p>If the code was entered correctly, but the method returns <a href="/constructor/auth.authorizationSignUpRequired">auth.authorizationSignUpRequired</a>, it means that account with this phone number doesn&#39;t exist yet: user needs to provide basic information, accept terms of service and then the new user registration method (<a href="/method/auth.signUp">auth.signUp</a>) must be invoked.</p>
<h3><a class="anchor" name="2fa" href="#2fa"><i class="anchor-icon"></i></a>2FA</h3>
<p>When trying to sign in using <a href="/method/auth.signIn">auth.signIn</a>, an <a href="/method/auth.signIn#possible-errors">error 400 SESSION_PASSWORD_NEEDED</a> may be returned, if the user has two-factor authentication enabled.<br>In this case, instructions for <a href="/api/srp">SRP 2FA authentication</a> must be followed.</p>
2022-02-24 19:51:11 +01:00
<p>To set up two-factor authorization on an already authorized account, follow the <a href="/api/srp">SRP 2FA authentication docs</a>.</p>
2024-05-06 15:31:53 +02:00
<h3><a class="anchor" name="confirming-login" href="#confirming-login"><i class="anchor-icon"></i></a>Confirming login</h3>
<pre><code>authorization#ad01d61d flags:# current:flags.0?true official_app:flags.1?true password_pending:flags.2?true encrypted_requests_disabled:flags.3?true call_requests_disabled:flags.4?true unconfirmed:flags.5?true hash:long device_model:string platform:string system_version:string api_id:int app_name:string app_version:string date_created:int date_active:int ip:string country:string region:string = Authorization;
2024-02-10 15:30:03 +01:00
2024-05-06 15:31:53 +02:00
account.authorizations#4bff8ea0 authorization_ttl_days:int authorizations:Vector&lt;Authorization&gt; = account.Authorizations;
2024-02-10 15:30:03 +01:00
2024-05-06 15:31:53 +02:00
updateNewAuthorization#8951abef flags:# unconfirmed:flags.0?true hash:long date:flags.0?int device:flags.0?string location:flags.0?string = Update;
2024-02-10 15:30:03 +01:00
---functions---
2024-05-06 15:31:53 +02:00
account.getAuthorizations#e320c158 = account.Authorizations;
2024-02-10 15:30:03 +01:00
2024-05-06 15:31:53 +02:00
account.changeAuthorizationSettings#40f48462 flags:# confirmed:flags.3?true hash:long encrypted_requests_disabled:flags.0?Bool call_requests_disabled:flags.1?Bool = Bool;
2024-02-10 15:30:03 +01:00
2024-05-06 15:31:53 +02:00
account.resetAuthorization#df77f3bc hash:long = Bool;</code></pre>
<p>When logging in, other logged-in sessions will receive an <a href="/constructor/updateNewAuthorization">updateNewAuthorization</a> update.<br>If the <code>unconfirmed</code> flag is set, clients should display a notification, asking the user if they recognize the session. </p>
<p>If the user clicks on the Yes button, invoke <a href="/method/account.changeAuthorizationSettings">account.changeAuthorizationSettings</a> with the new session&#39;s <code>hash</code> and the <code>confirmed</code> flag set, confirming the specified session. </p>
<p>If the user clicks on the No button, invoke <a href="/method/account.resetAuthorization">account.resetAuthorization</a> with the new session&#39;s <code>hash</code>, logging out the specified session. </p>
<p>If no action is taken by the user, the session will be autoconfirmed <code>authorization_autoconfirm_period</code> seconds after login (see the associated <a href="/api/config#authorization-autoconfirm-period">client configuration parameter &raquo;</a>). </p>
<h3><a class="anchor" name="invalidating-login-codes" href="#invalidating-login-codes"><i class="anchor-icon"></i></a>Invalidating login codes</h3>
<p>Telegram&#39;s servers will automatically invalidate login codes if they are sent by the user to another Telegram chat, either by forwarding them or by sending them inside of a message: however, clients should also manually and immediately invalidate login codes if the user attempts to screenshot or forward a message sent by the login notification service user (ID <code>777000</code>) containing login codes. </p>
2024-02-10 15:30:03 +01:00
<p>If an incoming message that is:</p>
<ul>
<li>Sent by the login notification service user (ID <code>777000</code>)</li>
<li>AND is a text message (not a media)</li>
2024-05-06 15:31:53 +02:00
<li>AND contains one or more login codes, defined as a sequence of 5 to 7 decimal digits, optionally interleaved with or followed by any number of <code>-</code> characters (<a href="https://github.com/tdlib/td/blob/07c1d53a6d3cb1fad58d2822e55eef6d57363581/td/telegram/MessagesManager.cpp#L6513">example implementation &raquo;</a>)</li>
2024-02-10 15:30:03 +01:00
</ul>
<p>Is either:</p>
<ul>
<li>Screenshotted by the user</li>
<li>OR forwarded by the user to any chat</li>
</ul>
2024-05-06 15:31:53 +02:00
<p><a href="/method/account.invalidateSignInCodes">account.invalidateSignInCodes</a> should be invoked, passing the extracted login <code>codes</code> (excluding any <code>-</code> characters). </p>
2024-02-10 15:30:03 +01:00
<pre><code>---functions---
2024-05-06 15:31:53 +02:00
account.invalidateSignInCodes#ca8ae8ba codes:Vector&lt;string&gt; = Bool;</code></pre>
<h3><a class="anchor" name="test-accounts" href="#test-accounts"><i class="anchor-icon"></i></a>Test Accounts</h3>
2022-02-24 19:51:11 +01:00
<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>
2024-02-10 15:30:03 +01:00
<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 <a href="https://my.telegram.org/apps">API development tools</a> panel after <a href="https://core.telegram.org/api/obtaining_api_id#obtaining-api-id">api_id was obtained</a>, <a href="https://core.telegram.org/mtproto/transports#uri-format">URI format</a> for HTTPS/WebSocket transport).</p>
2022-02-24 19:51:11 +01:00
<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>
</blockquote>
2024-05-06 15:31:53 +02:00
<h3><a class="anchor" name="we-are-authorized" href="#we-are-authorized"><i class="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&#39;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>
2022-02-24 19:51:11 +01:00
<p>Only a small portion of the API methods are available to <strong>unauthorized</strong> users:</p>
<ul>
<li><a href="/method/auth.sendCode">auth.sendCode</a></li>
<li><a href="/method/auth.resendCode">auth.resendCode</a></li>
<li><a href="/method/account.getPassword">account.getPassword</a></li>
<li><a href="/method/auth.checkPassword">auth.checkPassword</a></li>
<li><a href="/method/auth.checkPhone">auth.checkPhone</a></li>
<li><a href="/method/auth.signUp">auth.signUp</a></li>
<li><a href="/method/auth.signIn">auth.signIn</a></li>
<li><a href="/method/auth.importAuthorization">auth.importAuthorization</a></li>
<li><a href="/method/help.getConfig">help.getConfig</a></li>
<li><a href="/method/help.getNearestDc">help.getNearestDc</a></li>
<li><a href="/method/help.getAppUpdate">help.getAppUpdate</a></li>
<li><a href="/method/help.getCdnConfig">help.getCdnConfig</a></li>
<li><a href="/method/langpack.getLangPack">langpack.getLangPack</a></li>
<li><a href="/method/langpack.getStrings">langpack.getStrings</a></li>
<li><a href="/method/langpack.getDifference">langpack.getDifference</a></li>
<li><a href="/method/langpack.getLanguages">langpack.getLanguages</a></li>
<li><a href="/method/langpack.getLanguage">langpack.getLanguage</a></li>
</ul>
2024-05-06 15:31:53 +02:00
<p>Other methods will result in an error: <a href="/api/errors#401-unauthorized"><strong>401 UNAUTHORIZED</strong></a>.</p>
</div>
2022-02-24 19:51:11 +01:00
</div>
</div>
</div>
<div class="footer_wrap">
<div class="footer_columns_wrap footer_desktop">
<div class="footer_column footer_column_telegram">
<h5>Telegram</h5>
<div class="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
</div>
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
<ul>
<li><a href="//telegram.org/faq">FAQ</a></li>
2022-09-09 12:10:24 +02:00
<li><a href="//telegram.org/privacy">Privacy</a></li>
2022-09-09 23:58:59 +02:00
<li><a href="//telegram.org/press">Press</a></li>
2022-02-24 19:51:11 +01:00
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
<ul>
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
2022-09-09 23:58:59 +02:00
<li><a href="//telegram.org/android">Android</a></li>
<li><a href="//telegram.org/dl/web">Mobile Web</a></li>
2022-02-24 19:51:11 +01:00
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
<ul>
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
<li><a href="//macos.telegram.org/">macOS</a></li>
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
</ul>
</div>
<div class="footer_column footer_column_platform">
<h5><a href="/">Platform</a></h5>
<ul>
<li><a href="/api">API</a></li>
<li><a href="//translations.telegram.org/">Translations</a></li>
<li><a href="//instantview.telegram.org/">Instant View</a></li>
</ul>
</div>
</div>
<div class="footer_columns_wrap footer_mobile">
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/blog">Blog</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps">Apps</a></h5>
</div>
<div class="footer_column">
<h5><a href="/">Platform</a></h5>
</div>
<div class="footer_column">
2024-02-15 09:51:10 +01:00
<h5><a href="//telegram.org/press">Press</a></h5>
2022-02-24 19:51:11 +01:00
</div>
</div>
</div>
</div>
2022-12-10 23:50:15 +01:00
<script src="/js/main.js?47"></script>
2022-02-24 19:51:11 +01:00
<script src="/js/jquery.min.js?1"></script>
<script src="/js/bootstrap.min.js?1"></script>
<script>window.initDevPageNav&&initDevPageNav();
backToTopInit("Go up");
removePreloadInit();
</script>
</body>
</html>