telegram-crawler/data/corefork.telegram.org/api/auth.html

210 lines
16 KiB
HTML
Raw Normal View History

2022-02-23 16:30:26 +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.">
<link rel="shortcut icon" href="/favicon.ico?4" type="image/x-icon" />
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
2022-04-18 22:44:16 +02:00
<link href="/css/telegram.css?226" rel="stylesheet" media="screen">
2022-02-23 16:30:26 +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 -->
2022-03-24 12:19:10 +01: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>
<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-23 16:30:26 +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>
2022-03-24 12:19:10 +01: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 is 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 logout tokens are used: </p>
<h4><a class="anchor" name="logout-tokens" href="#logout-tokens"><i class="anchor-icon"></i></a>Logout tokens</h4>
<p>When invoking <a href="/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>At all times, the logout token database should contain at most 20 tokens: evict older tokens as new tokens are added.<br>When invoking <a href="/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&#39;re trying to login into and the token hasn&#39;t expired, <a href="/method/auth.sendCode">auth.sendCode</a> will directly return a <code>SESSION_PASSWORD_NEEDED</code> RPC error, directly asking the user to <a href="#2fa">enter the 2FA password</a>, without sending any authorization code. </p>
2022-03-09 16:21:25 +01:00
<p>Otherwise, the system will send an authorization code using the following logic:</p>
2022-03-24 12:19:10 +01:00
<h4><a class="anchor" name="code-types" href="#code-types"><i class="anchor-icon"></i></a>Code types</h4>
2022-03-09 16:21:25 +01:00
<p>The system will automatically choose how to send the authorization code; there are multiple possible ways the code can arrive:</p>
2022-02-23 16:30:26 +01:00
<ul>
2022-03-24 12:19:10 +01:00
<li><a href="/constructor/auth.loggedOut">Logout tokens &raquo;</a></li>
2022-02-23 16:30:26 +01:00
<li><a href="/constructor/auth.sentCodeTypeApp">Telegram code</a></li>
<li><a href="/constructor/auth.sentCodeTypeSms">SMS code</a></li>
2022-02-24 22:12:16 +01:00
<li><a href="/constructor/auth.sentCodeTypeCall">Phone call</a>: a synthesized voice will tell the user which verification code to input.</li>
2022-03-24 12:19:10 +01:00
<li><a href="/constructor/auth.sentCodeTypeFlashCall">Flash phone call</a>: the code will be sent via a flash phone call, that will be closed immediately.<br>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 <a href="/constructor/auth.sentCodeTypeFlashCall">auth.sentCodeTypeFlashCall</a>).</li>
2022-02-24 22:12:16 +01:00
<li><a href="/constructor/auth.sentCodeTypeMissedCall">Missed phone call</a>: the code will be sent via a flash phone call, that will be closed immediately. The last digits of the phone number that calls are the code that must be entered manually by the user.</li>
2022-02-23 16:30:26 +01:00
</ul>
2022-03-24 12:19:10 +01:00
<p>The <a href="/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.<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>
2022-02-23 16:30:26 +01:00
<p>The returned <a href="/type/auth.SentCode">auth.SentCode</a> object will contain multiple parameters:</p>
<table class="table">
<tbody>
<tr>
<td><strong>flags</strong></td>
2022-03-24 12:19:10 +01:00
<td align="center"><a href="/type/%23">#</a></td>
2022-02-23 16:30:26 +01:00
<td>Flags, see <a href="/mtproto/TL-combinators#conditional-fields">TL conditional fields</a></td>
</tr>
<tr>
<td><strong>type</strong></td>
2022-03-24 12:19:10 +01:00
<td align="center"><a href="/type/auth.SentCodeType">auth.SentCodeType</a></td>
2022-02-23 16:30:26 +01:00
<td>Phone code type</td>
</tr>
<tr>
<td><strong>phone_code_hash</strong></td>
2022-03-24 12:19:10 +01:00
<td align="center"><a href="/type/string">string</a></td>
2022-02-23 16:30:26 +01:00
<td>Phone code hash, to be stored and later re-used with <a href="/method/auth.signIn">auth.signIn</a></td>
</tr>
<tr>
<td><strong>next_type</strong></td>
2022-03-24 12:19:10 +01: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-23 16:30:26 +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>
2022-03-24 12:19:10 +01:00
<td align="center"><a href="/mtproto/TL-combinators#conditional-fields">flags</a>.2?<a href="/type/int">int</a></td>
2022-02-23 16:30:26 +01:00
<td>Timeout for reception of the phone code</td>
</tr>
</tbody>
</table>
2022-03-24 12:19:10 +01: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="sign-in-sign-up" href="#sign-in-sign-up"><i class="anchor-icon"></i></a>Sign in/sign up</h3>
2022-02-23 16:30:26 +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>
2022-03-24 12:19:10 +01: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-23 16:30:26 +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>
2022-03-24 12:19:10 +01:00
<h4><a class="anchor" name="test-accounts" href="#test-accounts"><i class="anchor-icon"></i></a>Test Accounts</h4>
2022-02-23 16:30:26 +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>
2022-03-03 10:14:42 +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-23 16:30:26 +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>
2022-03-24 12:19:10 +01: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-23 16:30:26 +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>
2022-03-24 12:19:10 +01:00
<p>Other methods will result in an error: <a href="/api/errors#401-unauthorized"><strong>401 UNAUTHORIZED</strong></a>.</p>
</div>
2022-02-23 16:30:26 +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>
<li><a href="//telegram.org/blog">Blog</a></li>
<li><a href="//telegram.org/jobs">Jobs</a></li>
</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>
<li><a href="//telegram.org/dl/android">Android</a></li>
<li><a href="//telegram.org/dl/wp">Windows Phone</a></li>
</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="//core.telegram.org/">Platform</a></h5>
<ul>
<li><a href="//core.telegram.org/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="//core.telegram.org/">Platform</a></h5>
</div>
<div class="footer_column">
<h5><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)">Twitter</a></h5>
</div>
</div>
</div>
</div>
2022-04-15 15:43:57 +02:00
<script src="/js/main.js?45"></script>
2022-02-23 16:30:26 +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>