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

210 lines
14 KiB
HTML
Raw Normal View History

2021-09-09 20:46:07 +02: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">
2021-11-01 18:49:45 +01:00
<link href="/css/telegram.css?213" rel="stylesheet" media="screen">
2021-09-09 20:46:07 +02: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 -->
<p>Authorization is associated with a clients encryption key identifier: <strong>auth_key_id</strong>. No additional parameters need to be passed into methods following authorization. </p>
2021-09-10 18:27:56 +02:00
<p>To log in as a <a href="/bots">bot</a>, follow <a href="/api/bots">these instructions »</a>.</p>
<h3><a class="anchor" href="#sending-a-verification-code" id="sending-a-verification-code" name="sending-a-verification-code"><i class="anchor-icon"></i></a>Sending a verification code</h3>
2021-09-09 20:46:07 +02: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>
2021-09-10 18:27:56 +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 is then used as described <a href="/api/config#country-information-and-login-phone-patterns">here »</a>. </p>
<p>Authorization requires that a text message containing an authorization code first be sent to the users phone.<br>
This may be done using the <a href="/method/auth.sendCode">auth.sendCode</a> method.
The system will automatically choose how to send the authorization code; there are four possible ways the code can arrive:</p>
2021-09-09 20:46:07 +02:00
<ul>
<li><a href="/constructor/auth.sentCodeTypeApp">Telegram code</a></li>
<li><a href="/constructor/auth.sentCodeTypeSms">SMS code</a></li>
<li><a href="/constructor/auth.sentCodeTypeCall">Phone call</a>: a synthesized voice will tell the user which verification code to input</li>
2021-09-10 18:27:56 +02: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.
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>
2021-09-09 20:46:07 +02:00
</ul>
2021-09-10 18:27:56 +02:00
<p>The <a href="/method/auth.sendCode">auth.sendCode</a> 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 <a href="https://developers.google.com/identity/sms-retriever/overview">android SMS receiver APIs</a>.</p>
2021-09-09 20:46:07 +02: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>
2021-09-10 18:27:56 +02:00
<td style="text-align: center;"><a href="/type/%23">#</a></td>
2021-09-09 20:46:07 +02:00
<td>Flags, see <a href="/mtproto/TL-combinators#conditional-fields">TL conditional fields</a></td>
</tr>
<tr>
<td><strong>type</strong></td>
2021-09-10 18:27:56 +02:00
<td style="text-align: center;"><a href="/type/auth.SentCodeType">auth.SentCodeType</a></td>
2021-09-09 20:46:07 +02:00
<td>Phone code type</td>
</tr>
<tr>
<td><strong>phone_code_hash</strong></td>
2021-09-10 18:27:56 +02:00
<td style="text-align: center;"><a href="/type/string">string</a></td>
2021-09-09 20:46:07 +02: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>
2021-09-10 18:27:56 +02:00
<td style="text-align: center;"><a href="/mtproto/TL-combinators#conditional-fields">flags</a>.1?<a href="/type/auth.CodeType">auth.CodeType</a></td>
2021-09-09 20:46:07 +02: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>
2021-09-10 18:27:56 +02:00
<td style="text-align: center;"><a href="/mtproto/TL-combinators#conditional-fields">flags</a>.2?<a href="/type/int">int</a></td>
2021-09-09 20:46:07 +02:00
<td>Timeout for reception of the phone code</td>
</tr>
</tbody>
</table>
2021-09-10 18:27:56 +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>.
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>.
To cancel the verification code use <a href="/method/auth.cancelCode">auth.cancelCode</a>.</p>
<h3><a class="anchor" href="#sign-insign-up" id="sign-insign-up" name="sign-insign-up"><i class="anchor-icon"></i></a>Sign in/sign up</h3>
2021-09-09 20:46:07 +02: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>
2021-09-10 18:27:56 +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'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" href="#2fa" id="2fa" name="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.
In this case, instructions for <a href="/api/srp">SRP 2FA authentication</a> must be followed.</p>
2021-09-09 20:46:07 +02: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>
2021-09-10 18:27:56 +02:00
<h4><a class="anchor" href="#test-phone-numbers" id="test-phone-numbers" name="test-phone-numbers"><i class="anchor-icon"></i></a>Test Phone Numbers</h4>
2021-09-09 20:46:07 +02: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>
<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 availble 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>
<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 XXXXXX as the login confirmation code (the DC number, repeated six 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>
2021-09-10 18:27:56 +02:00
<h3><a class="anchor" href="#we-are-authorized" id="we-are-authorized" name="we-are-authorized"><i class="anchor-icon"></i></a>We are authorized</h3>
2021-09-09 20:46:07 +02:00
<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 users 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>
<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>
2021-09-10 18:27:56 +02:00
<p>Other methods will result in an error: <a href="/api/errors#401-unauthorized"><strong>401 UNAUTHORIZED</strong></a>.</p></div>
2021-09-09 20:46:07 +02: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>
<script src="/js/main.js?42"></script>
<script src="/js/jquery.min.js?1"></script>
<script src="/js/bootstrap.min.js"></script>
<script>window.initDevPageNav&&initDevPageNav();
backToTopInit("Go up");
removePreloadInit();
</script>
</body>
</html>