결론부터
- 1exportLoginToken 의 토큰을 tg://login 주소 QR 로 띄운다.
- 2토큰은 짧게 만료 — 화면을 켠 동안 새 QR 로 계속 바꾼다.
- 3updateLoginToken 이 오면 한 번 더 불러 성공·데이터 센터 이동을 받는다.
QR 로그인이란
PC 앱이나 웹에서 전화번호·코드를 치는 대신, 화면의 QR 코드를 이미 로그인된 휴대폰 텔레그램으로 찍어 로그인하는 방식입니다. 내 앱에 이 방식을 넣으면 사용자는 코드를 기다릴 필요가 없습니다. 사용자 쪽 사용법은 PC 설치·QR 로그인에 있습니다.
로그인을 받는 쪽(내 앱)의 순서
auth.exportLoginToken을 부릅니다(api_id·api_hash, 이미 로그인한 다른 계정이 있으면 그 ID 들을 빼 달라고 함께 보냄). 서버는 토큰과 만료 시각을 돌려줍니다.- 토큰을 base64url 로 바꿔
tg://login?token=…주소를 만들고, 이 주소를 QR 코드로 화면에 띄웁니다. - 토큰은 짧게 만료됩니다. 응답에 함께 온 만료 시각이 지나기 전에 다시 exportLoginToken 을 불러 새 QR 로 바꿔 줍니다 — 화면을 켜 둔 동안 계속.
- 사용자가 휴대폰으로 찍어 허락하면 내 앱에
updateLoginToken업데이트가 옵니다. 이때 exportLoginToken 을 한 번 더 부릅니다. - 답이 성공(loginTokenSuccess)이면 로그인 끝. 다른 데이터 센터로 옮기라(loginTokenMigrateTo)는 답이면 그 데이터 센터에 연결해
auth.importLoginToken으로 마무리합니다(데이터 센터). - 계정에 2단계 인증이 켜져 있으면 여기서
SESSION_PASSWORD_NEEDED가 오고, 비밀번호 확인으로 이어집니다(로그인 흐름).
찍는 쪽(휴대폰)의 일
QR 을 찍은 공식 앱은 그 토큰으로 auth.acceptLoginToken 을 불러 로그인을 허락합니다. 직접 만든 앱에서 '다른 기기 로그인 허락' 기능을 넣는다면 이 메서드를 씁니다. 허락하기 전에 어떤 앱·어떤 위치에서 로그인하려는지 사용자에게 꼭 보여 줍니다.
자주 막히는 곳
| 증상 | 원인과 처리 |
|---|---|
| 찍었는데 아무 일도 없다 | QR 이 이미 만료됐다 — 만료 전에 새 QR 로 바꾸는지 확인 |
| 허락 뒤 로그인이 안 끝난다 | updateLoginToken 을 받고 exportLoginToken 을 다시 부르지 않았다 |
| 다른 데이터 센터로 가라는 답 | 그 데이터 센터에서 importLoginToken — 새 연결이 필요하다 |
| 토큰 오류(400) | 만료·이미 쓴 토큰 — QR 을 새로 만든다 |
자주 묻는 질문
텔레그램 QR 로그인 토큰은 얼마나 유효한가요?
짧게 만료됩니다. exportLoginToken 응답의 만료 시각이 지나기 전에 다시 불러 새 QR 로 바꿉니다.
QR 을 찍었는데 로그인이 안 끝나요.
updateLoginToken 을 받은 뒤 exportLoginToken 을 한 번 더 불러야 성공 결과가 옵니다.
loginTokenMigrateTo 가 왔어요.
계정이 다른 데이터 센터에 있다는 뜻입니다. 그 데이터 센터에 연결해 auth.importLoginToken 을 부릅니다.
QR 로그인에도 2단계 인증이 필요한가요?
켜져 있는 계정이면 SESSION_PASSWORD_NEEDED 가 오고 비밀번호 확인으로 이어집니다.
참고한 공식 문서
요약
한눈에 정리
- 1토큰
exportLoginToken · QR.
- 2갱신
만료 전 새 QR.
- 3마무리
update 뒤 다시 부르기.
최종 수정 2026-10-06
