Telegram api_id 하나로 여러 계정·프로젝트에 써도 될까

Telegram API를 사용할 때 api_id 발급 구조부터 session, 서버의 식별 방식, 제재 기준과 주의사항을 정리한다.

Telegram API의 api_id와 api_hash

텔레그램 관련 앱을 작성하려면 api_id가 필요하다. 이전에 사용할 전화번호에 대해 발급받은 적이 없으면 my.telegram.org에 접속해서 your phone number를 입력하면 웹 로그인 코드가 텔레그램을 통해 수신된다. 이 코드를 입력하고 App title, Short name 등 메타 정보를 입력하면 api_id와 api_hash가 발급된다. 텔레그램의 본질은 전화번호이므로 api_id 발급의 출발점도 전화번호이고, 하나의 전화번호에는 하나의 api_id만 발급된다. 발급 이후 App title이나 Short name을 바꾸더라도, 이미 생성된 api_id와 api_hash는 변경되지 않는다.

Telegram에서 말하는 “앱(App)”의 정확한 의미

텔레그램 문서와 my.telegram.org에서는 API development tools에서 api_id를 발급받을 때 “App”이라는 표현을 사용한다. api_id를 발급받은 상태에서 API development tools 페이지(링크)로 이동하면 App Configuration 제목 아래에 App api_id, App api_hash, App title, Short name 등이 보인다. 여기서 말하는 "App"은 우리가 흔히 생각하는 개별 모바일 앱이나 웹 서비스 하나를 의미하지 않는다. 텔레그램 응용 프로그램을 작성하게 되면 자연스럽게 텔레그램 서버에 접속해서 메시지를 처리하게 된다. 위에서 텔레그램의 "App"은 Telegram 서버 입장에서 API 요청을 받았을 때 그 출처를 구분하는 식별자다. api_id는 텔레그램 서버에 서비스를 요청하는 클라이언트 식별자라고 생각하면 되고, 텔레그램 서버는 api_id별로 어떻게 서비스를 제공할지 판단하게 된다.

“api_id를 새로 판다”?

같은 전화번호로는 새로운 api_id를 만들 수 없다. 이 표현의 실제 의미는 새로운 전화번호로 텔레그램 계정을 생성하고 그 계정으로 my.telegram.org에 로그인해 새로운 api_id / api_hash를 발급받는 것을 말한다. 위에서 언급한 것처럼 api_id는 전화번호 단위로 하나뿐이므로 새 api_id를 원하면 새 전화번호가 필요하다.

api_id와 Telegram 계정(전화번호)의 관계

api_id는 발급과 관리 권한이 특정 전화번호에 귀속되지만, 이 api_id를 사용하는 앱을 그 전화번호를 가진 사람만 구동할 수 있다는 것은 아니다. 다른 텔레그램 계정(전화번호)을 가진 사람도 그 앱을 사용할 수 있다.

일반 사용자의 텔레그램 앱 인증 단계

예를 들어 개발자가 api_id를 발급받아서 텔레그램 관련 웹앱을 만들었다고 하자. 일반 사용자는 그 웹앱 URL에 접속하면 자신의 전화번호를 입력하도록 안내받고, 입력과 동시에 텔레그램 계정으로 인증번호를 수신받는다. 인증번호를 웹앱에 입력하면 정상 로그인이 완료된다. 이때 웹앱 내부에서 session 값이 클라이언트에 저장되고, 이후 이 session 정보를 통해 연결된다.

session이란 무엇인가

session은 api_id + 특정 Telegram 계정 조합으로 생성되는 인증 결과물이다.

session = api_id + Telegram 계정(user_id) + 로그인 과정에서 생성된 auth key

session에는 다음과 같은 정보가 포함된다.

• 해당 계정의 인증 상태
• 암호화 키
• 연결된 Telegram 데이터센터 정보
• 재로그인 없이 요청할 수 있는 권한 정보 사용자가 같은 전화번호로 api_id가 다른 여러 텔레그램 앱을 사용 중이면 당연히 session은 공유되지 않는다. 같은 api_id를 같은 계정으로 여러 환경에서 사용하는 경우도 별도로 OTP 로그인을 하면 각각 session이 만들어진다.

AUTH_KEY_DUPLICATED

AUTH_KEY_DUPLICATED는 텔레그램 서버의 보안 동작으로 “같은 auth key가 동시에 서로 다른 연결 컨텍스트에서 사용되고 있다”라는 의미다. 두 장치에서 동일한 session 값(파일)을 복사해서 동시에 실행되는 경우 흔하게 발생한다. 이는 장치 정보가 달라서 발생하는 것이 아니라 같은 auth key를 가지는 session 값이 동시에 사용되기 때문이다. 특히 Kubernetes에서 auto scaling을 하게 되면 pod 여러 개가 동시에 기동할 때 발생 가능하다.

하나의 api_id를 여러 프로젝트·장치에서 사용할 수 있다

하나의 api_id를 사용해 A 프로젝트와 B 프로젝트를 동시에 운영할 수 있고, 서로 다른 서버나 PC, 컨테이너에서도 실행할 수 있으며 서로 다른 텔레그램 계정으로 각각 로그인할 수도 있다. 텔레그램 서버 입장에서는 이 모든 요청은 동일한 api_id를 사용하는 클라이언트 그룹으로 보인다.

Telegram 서버는 무엇을 기준으로 이상 동작을 판단하는가

텔레그램 앱이 이상 동작을 하는 경우 텔레그램 서버가 탐지해서 속도나 서비스 제한을 건다. 텔레그램은 단순히 api_id 하나만 보고 제재하지 않는다. 실제 판단에는 다음 요소들이 함께 사용된다.

• Telegram 계정(전화번호)
• api_id
• 요청 빈도, 패턴, 반복성
• 로그인·OTP 시도 방식
• IP 및 네트워크 환경
• 시간에 따른 누적 행동 기록

이 중 전화번호는 개별 계정 제재의 기준이고, api_id 기준으로 클라이언트 전체의 신뢰도를 관리한다.

api_id가 문제가 생겼을 때 나타나는 전형적인 증상

OTP 요청, 로그인 시도를 과도하게 반복하거나 FloodWait을 무시하고 반복 재시도하거나 사람이 직접 조작하는 패턴이 아닌 대량 자동화 패턴을 장기간 유지하면 api_id 신뢰도가 낮아진다. api_id의 신뢰도가 낮아지면 다음과 같은 현상이 나타날 수 있다.

• 여러 계정에서 동시에 FloodWait 발생
• OTP 코드 수신 지연 또는 실패
• 일부 API만 비정상적으로 제한됨
• 로그인은 되지만 메시지 전송·조회가 불안정

텔레그램은 api_id에 대한 명확한 경고를 주지 않고, 점진적으로 제한을 강화해서 사용 불가 상태로 만든다.

Telegram 앱 구현 시 인증 정보 설정 기능

개발 과정에서는 session 정보를 복사해서 사용하는 경우가 많으므로, 텔레그램 관련 로그에서 AUTH_KEY_DUPLICATED가 발생하면 session 값을 새로 받아서 저장하는 기능을 추가하면 편리하다. 또한 사용중인 api_id에 성능 제한이 생긴 것 같으면 새로운 api_id와 api_hash로 대체해서 앱을 재시작하는 기능이 있으면 편리할 것이다.

(끝)