> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/guide/authentication/intro.md). # 토스 로그인 앱인토스에서 토스 회원을 한 번에 연동해 보세요. 한 번의 동의로 가입부터 로그인, 정보 제공까지 이어져 토스 회원 연동을 간단하게 구현할 수 있어요. *** ### 토스 로그인을 사용하면 어떤 점이 좋나요 * 별도의 가입 폼 없이 바로 가입과 로그인이 이뤄져 매끄러운 회원가입 경험을 만들 수 있어요. * 토스에서 직접 제공하는 신뢰도 높은 사용자 정보를 활용할 수 있어요. * 재방문할 때 자동 로그인이나 원클릭 로그인이 가능해요. * 앱을 다시 설치하거나 기기를 바꿔도 같은 사용자로 매칭돼 고객 문의 대응 부담이 줄어들어요. {% hint style="info" %} **꼭 확인해 주세요** * 미니앱에서 로그인 기능은 토스 로그인만 사용할 수 있어요. 자사 로그인이나 다른 간편 로그인 방식은 사용할 수 없어요. * 기능성 푸시와 알림, 프로모션, 토스페이를 사용하려면 토스 로그인을 반드시 연동해야 해요. {% endhint %}
*** ### 콘솔에서 설정하기 토스 로그인을 원활히 사용하려면 **콘솔에서 계약 → 설정** 순서로 진행해 주세요. #### **1. 약관 동의** 토스 로그인 사용을 위해서는 **약관에 동의해야 해요.** 약관 동의는 앱인토스 콘솔에서 진행이 가능하며, **대표 관리자로 지정된 분**의 계정에서만 가능해요. * 약관 동의 방법 * 앱인토스 콘솔 접속 → 대표 관리자 계정 로그인 → 워크스페이스 선택 → 미니앱 선택 → 좌측 메뉴 중 '토스 로그인' 선택 후 '약관 확인하기' 를 클릭해서 아래 화면에서 약관 동의 진행
#### **2. 설정하기** 로그인 연동을 위해 콘솔에서 **사전 설정**을 완료해 주세요. \ 입력한 정보를 기반으로 **사용자 약관 동의 화면**이 자동으로 구성돼요.
**① 연동할 서비스 — 기존 로그인과 연동하기** 이미 토스 로그인을 사용 중인 서비스가 있을 경우 노출되는 영역이에요. 기존 서비스의 회원 식별자(`userKey`)를 **앱인토스 토스 로그인과 동일하게 설정**할 수 있어요. 목록에서 서비스 이름을 선택하면, 선택한 서비스의 `userKey` 값이 **동일하게 매핑돼요.** {% hint style="info" %} **회원을 관리해보세요** 토스 로그인을 연동하면 회원 정보를 쉽게 조회할 수 있어요. 사용자 정보 받기 API를 통해 사용자 식별자 `userKey`를 전달받을 수 있으며, `userKey`는 회원별 유니크한 값으로 **통합 회원 관리**에 유용해요. 단, `userKey`는 해당 앱 내에서만 유일한 값이에요. 동일한 사용자라도 앱이 다르면 `userKey`가 달라질 수 있어요. {% endhint %} **② 동의 항목 — 사용자 권한 범위 설정** 토스 로그인을 통해 수집할 **사용자 권한(스코프)** 을 선택해 주세요. {% hint style="info" %} **꼭 확인해 주세요** 이름, 이메일, 성별 외의 항목을 선택한 경우, **연결 끊기 콜백 정보**를 반드시 입력해야 해요. {% endhint %} | 항목 | 설명 | | ---------------------- | ------------------------------------------------------------ | | 이름 (USER\_NAME) | 사용자의 이름이에요. | | 이메일 (USER\_EMAIL) | 사용자의 이메일이에요. (토스 가입 시 필수가 아니어서 값이 없을 수 있고, 이 경우 null로 전달돼요.) | | 성별 (USER\_GENDER) | 사용자의 성별이에요. | | 생일 (USER\_BIRTHDAY) | 사용자의 생년월일이에요. | | 국적 (USER\_NATIONALITY) | 사용자의 국적이에요. | | 전화번호 (USER\_PHONE) | 사용자의 전화번호예요. | | CI (USER\_CI) | 사용자를 식별하는 고유한 KEY 값이에요. (Connection Information) | {% hint style="info" %} **CI란?** CI(Connection Information)는 본인인증 기관에서 발급하는 **고유 식별값**이에요. 동일한 사용자가 여러 서비스에 가입하더라도, **같은 본인으로 식별할 수 있도록 생성되는 불변값**이에요. CI는 사용자 실명 인증이 필요한 서비스에서 **중복가입 방지나 본인 식별** 목적으로 자주 활용돼요. 개인정보보호법상 **개인식별정보(PII)** 에 해당하므로, 저장하거나 사용할 때 반드시 **암호화 및 최소 수집 원칙**을 지켜야 해요. {% endhint %} **③ 약관 등록** {% hint style="info" %} **주의해 주세요** 이 영역은 **법적 요건을 충족해야 하는 부분**이에요. 서비스 성격에 따라 내용이 달라질 수 있으니 **최신 법령과 가이드라인을 확인하고, 법률 자문을 받는 것**을 권장해요. {% endhint %} 앱인토스에서 서비스를 운영하려면 약관을 등록해야 해요. **토스 로그인 필수 약관(서비스 약관 / 개인정보 제3자 제공 동의)** 은 자동으로 포함되며, **파트너사 서비스 약관 / 개인정보 수집·이용 동의 / 마케팅 정보 수신 동의(선택)** 등은 직접 등록해야 해요. 서비스 목적에 맞는 **정확한 약관 링크**를 첨부해 주세요. 약관 유형은 기본 제공 예시 중에서 선택하거나 직접 입력할 수 있어요. 약관을 구분해서 관리하고 싶다면 직접 입력하는 걸 추천드려요. **등록 가능한 약관 예시** * **(1) 서비스 이용약관**: 권리·의무, 책임 범위, 중단/종료, 분쟁 해결, 약관 변경 고지, (유료 시) 결제/환불 규정 * **(2) 개인정보 수집·이용 동의**: 수집 항목, 이용 목적, 보유·이용 기간, 동의 거부 시 불이익 * **(3) 마케팅 정보 수신 동의(선택)**: 수집 항목, 이용 목적, 보유 기간, 거부 시 불이익, 전자적 전송매체 광고 수신 동의 * **(4) 야간 혜택 수신 동의(선택)**: 야간(21:00\~08:00) 발송 여부 명시 모든 약관 링크가 **정확히 연결**되고, 화면에 **명확하게 노출**되는지 확인해 주세요. **④ 연결 끊기 콜백 정보** 사용자가 토스앱에서 **로그인 연결을 해제**하면, 등록한 **콜백 URL**로 이벤트를 받을 수 있어요. {% hint style="info" %} **참고하세요** 사용자가 연결 해제를 하면 토스는 **동의 약관·로그인 정보**를 모두 삭제해요. 서비스에서도 세션이나 토큰 정리 등 후처리를 꼭 해 주세요. 또한, 사용자가 토스앱에서 로그인 연결을 해제하면 서비스에서도 **자동 로그아웃 처리** 또는 **재로그인 요청 안내**를 제공하는 걸 권장해요. 예를 들어, "토스 연결이 해제되어 로그인이 필요합니다." 같은 문구를 노출해 주세요. {% endhint %} | 항목 | 설명 | | ------------- | --------------------------------------------------- | | 콜백 URL | 사용자가 로그인 연결을 해제했을 때 호출할 URL이에요. | | HTTP 메서드 | `GET` 또는 `POST` 중 하나를 선택해 주세요. | | Basic Auth 헤더 | 호출 시 base64로 인코딩돼요. 디코딩 후 콘솔에 입력한 값과 일치하는지 검증해 주세요. | **연결 끊기 이벤트 경로** 사용자가 토스앱에서 로그인 연결을 해제하는 경로는 총 **3가지**예요. 콜백 요청 시 `referrer`값으로 구분할 수 있어요. | referrer | 설명 | | ------------------ | ------------------------------------------------------------------------------------------------------------------------ | | `UNLINK` | 사용자가 **앱에서 직접 연결을 끊었을 때** 호출돼요. 미니앱에서는 이 이벤트를 받으면 **로그아웃 처리**를 해 주세요. (경로: 토스 앱 > 설정 > 인증 및 보안 > 토스로 로그인한 서비스 > '연결 끊기') | | `WITHDRAWAL_TERMS` | 사용자가 **로그인 서비스 약관을 철회할 때** 호출돼요. (경로: 토스 앱 > 설정 > 법적 정보 및 기타 > 약관 및 개인정보 처리 동의 > 서비스별 동의 내용 : "토스 로그인" > '동의 철회하기') | | `WITHDRAWAL_TOSS` | 사용자가 **토스 회원을 탈퇴할 때** 호출돼요. | #### **3. 복호화 키 확인하기**
토스 로그인 정보 등록이 완료되면 **복호화 키**를 확인할 수 있어요. 이 키는 토스 로그인 응답 데이터를 복호화할 때 사용돼요. **‘이메일로 복호화 키 받기’** 버튼을 눌러 안전하게 받아보세요. {% hint style="info" %} **유의사항** 복호화 키는 **민감한 보안 정보**예요. * 절대 외부에 노출하지 마세요. * 안전한 내부 비밀 저장소(Secret Manager 등)에 보관해 주세요. * 재발급이 필요한 경우, 채널톡으로 문의해 주세요. {% endhint %} *** ### 자체 웹/앱에 토스 로그인을 사용하고 싶어요 자체 웹/앱에 토스 로그인을 적용하려면 토스 인증 부서와의 별도 계약이 필요해요. 다만, 앱인토스에서 토스 로그인을 사용하는 파트너사의 경우에는 별도 계약 없이도 사용할 수 있어요. **1. 앱인토스 콘솔에서 토스 로그인 신청하기** 위 가이드를 확인한 뒤, 앱인토스 콘솔에서 토스 로그인을 먼저 신청해 주세요. **2. 필요한 정보를 작성해 Client ID 발급 요청하기** 아래 항목을 모두 작성해 토스 인증 부서()로 이메일을 보내 주세요. | 항목 | 설명 | 예시 | | ------------------- | ------------------------------------------------------------- | --------------------------------------- | | 웹/앱 여부 | 적용하려는 서비스 형태를 작성해 주세요 (웹, 앱, 또는 둘 다) | 웹, 앱 | | 회원 식별 키 | 사용자 식별에 사용할 키를 작성해 주세요 | CI, 이메일 | | 필요한 개인정보 항목 | 제공받고자 하는 개인정보 항목을 작성해 주세요(앱인토스 콘솔 > 토스 로그인 > 동의 항목을 참고해 주세요) | 이름, 이메일 주소 | | 약관 목록 | 사용할 약관의 제목, URL, 필수 여부를 작성해 주세요 | 이용약관 (필수) - | | redirect\_uri | 로그인 완료 후 이동할 URL을 작성해 주세요 | | | 연동 예정 앱 버전 | 제휴사 앱에도 도입하는 경우 앱 버전을 작성해 주세요 | iOS 3.2.0, Android 2.8.1 | | 로그인 연결 끊기 API 사용 여부 | 해당 API 사용 여부를 작성해 주세요 (미작성 시 '사용 안 함'으로 설정돼요) | 사용 안 함 | | 네트워크 정보 | VPN을 사용하거나 개발계 연동이 필요한 경우 별도 등록이 필요해요서버의 IP 또는 IP 대역을 작성해 주세요 | 123.45.67.89 | *** ### 개발 연동하기 > 토스 로그인 개발하기 > > > 인가 코드 발급(SDK), AccessToken 발급, 사용자 정보 조회 등 연동 방법을 확인할 수 있어요. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers-apps-in-toss.toss.im/guide/authentication/intro.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.