연동 준비하기

토스 로그인 API를 연동할 때 공통으로 알아야 하는 정보를 정리한 문서입니다. Client 등록 방법, 도메인, Scope, 약관 등록, 연결 끊기 콜백, API 공통 응답 형식을 다룹니다.

---

사전 준비

토스 로그인 연동을 위해 Client 등록이 필요합니다. cert.support@toss.im으로 아래 정보를 보내 주세요.

	항목	비고
1	웹/앱 여부	웹, 앱, 둘 다
2	회원 관리 키	CI, e-mail, 휴대폰번호 등
3	CI 용도	CI 저장 필요 여부
4	필요한 개인정보 목록	Scope 목록 참고
5	약관 목록	약관 제목과 약관 URL, 필수여부
6	접근 URL	URL
7	redirect_uri	완료 후 보내질 화면 URI
8	연동 예정인 앱 버전
9	로그인 연결 끊기 API 사용 유무	default는 사용안함으로 설정됨
10	네트워크 정보

위 정보를 전달하면 다음 세 가지를 발급받습니다. 이후 API 연동에 필요하므로 안전하게 보관해 주세요.

항목	용도
clientId	API 요청 시 클라이언트 식별에 사용합니다.
clientSecret	토큰 발급 요청 시 인증에 사용합니다.
개인정보 암호키	사용자 정보 응답을 복호화하는 데 사용합니다.

---

Domain 정보

https://oauth2.cert.toss.im

---

Scope 목록

토스 로그인을 통해 수집할 사용자 권한(scope)이에요. 아래 목록은 식별용 대문자 표기이며, API 요청 시에는 소문자(예: user_name)를 사용합니다.

항목	설명
이름 (USER_NAME)	사용자의 이름이에요.
이메일 (USER_EMAIL)	사용자의 이메일이에요. (토스 가입 시 필수가 아니어서 값이 없을 수 있고, 이 경우 null로 전달돼요.)
성별 (USER_GENDER)	사용자의 성별이에요.
생일 (USER_BIRTHDAY)	사용자의 생년월일이에요.
국적 (USER_NATIONALITY)	사용자의 국적이에요.
전화번호 (USER_PHONE)	사용자의 전화번호예요.
CI (USER_CI)	사용자를 식별하는 고유한 KEY 값이에요. (Connection Information)
DI (USER_DI)	사용자를 식별하는 고유한 KEY 값이에요. (Duplication Information)

---

CI란?

INFO

CI(Connection Information)는 본인인증 기관에서 발급하는 고유 식별값이에요. 동일한 사용자가 여러 서비스에 가입하더라도, 같은 본인으로 식별할 수 있도록 생성되는 불변값이에요.

CI는 사용자 실명 인증이 필요한 서비스에서 중복 가입 방지나 본인 식별 목적으로 자주 활용돼요.

개인정보보호법상 PII(개인식별정보) 에 해당하므로, 저장하거나 사용할 때 반드시 암호화 및 최소 수집 원칙을 지켜야 해요.

---

DI란?

INFO

DI(Duplication Information)는 본인인증 기관에서 발급하는 중복 가입 방지용 식별값이에요.

동일한 사용자가 같은 서비스에 여러 번 가입하는 것을 방지하기 위해 생성되며, 서비스 단위로 서로 다른 값이 생성돼요. 즉, 같은 사용자라도 서비스 A와 서비스 B의 DI는 서로 달라요.

DI는 주로 중복 회원 가입 방지 목적으로 사용되고, 개인정보보호법상 PII(개인식별정보) 에 해당하므로 CI와 마찬가지로 암호화 및 최소 수집 원칙을 반드시 지켜야 해요.

WARNING

토스 로그인에서는 DI 조회가 1회로 제한되며, 이후 조회가 필요한 경우 without-di API를 사용해야 해요.

---

약관 등록하기

WARNING

이 영역은 법적 요건을 충족해야 하는 부분이에요. 서비스 성격에 따라 내용이 달라질 수 있으니, 최신 법령과 가이드라인을 확인하고 법률 자문을 받는 것을 권장해요.

토스로그인 서비스를 운영하려면 약관을 등록해야 해요.

• 토스 로그인 필수 약관 (서비스 약관 / 개인정보 제3자 제공 동의 등)은 자동으로 포함돼요.
• 파트너사 서비스 약관 / 개인정보 수집·이용 동의 / 마케팅 정보 수신 동의(선택) 등은 직접 요청해야 해요.

서비스 목적에 맞는 정확한 약관 링크를 첨부해 주세요.

등록 가능한 약관 예시

• (1) 서비스 이용약관 — 권리·의무, 책임 범위, 중단/종료, 분쟁 해결, 약관 변경 고지 (유료 서비스의 경우 결제/환불 규정 포함)
• (2) 개인정보 수집·이용 동의 — 수집 항목, 이용 목적, 보유·이용 기간, 동의 거부 시 불이익
• (3) 마케팅 정보 수신 동의 (선택) — 수집 항목, 이용 목적, 보유 기간, 거부 시 불이익, 전자적 전송매체 광고 수신 동의

모든 약관 링크가 정확히 연결되고, 화면에 명확하게 노출되는지 반드시 확인해 주세요.

---

연결 끊기 콜백 정보

사용자가 토스 앱에서 로그인 연결을 해제하면, 등록한 콜백 URL로 이벤트를 받을 수 있어요.

INFO

사용자가 연결을 해제하면 토스는 동의 약관과 로그인 정보를 모두 삭제해요. 서비스에서도 세션이나 토큰 정리를 반드시 후처리해 주세요.

또한, 사용자가 토스 앱에서 로그인 연결을 해제하면 서비스에서도 자동 로그아웃 처리 또는 재로그인 요청 안내를 제공하는 것을 권장해요.

예: "토스 연결이 해제되어 로그인이 필요합니다."

연결 끊기 콜백 설정 항목

항목	설명
콜백 URL	사용자가 로그인 연결을 해제했을 때 호출할 URL이에요.
HTTP 메서드	GET 또는 POST 중 하나를 선택해 주세요.
Basic Auth 헤더	호출 시 base64로 인코딩돼요. 디코딩 후 콘솔에 입력한 값과 일치하는지 검증해 주세요.

---

전체 흐름 (Sequence Diagram)

로그인 / 회원가입

AccessToken 재발급

로그인 연결 끊기 (Client Credentials 방식)

약관 동의 철회 (Client Credentials 방식)

---

API 공통 응답

사용자 정보 조회, 로그인 연결 끊기, 약관 관리 API는 아래 공통 응답 형식을 사용합니다.

성공

resultType이 SUCCESS로 설정되며, 응답 데이터는 success 하위에 포함됩니다.

{
  "resultType": "SUCCESS",
  "success": {
    "sample": "data"
  }
}

실패

resultType이 FAIL로 설정되며, 실패 사유는 error 하위에 포함됩니다.

{
  "resultType": "FAIL",
  "error": {
    "errorCode": "INVALID_PARAMETER",
    "reason": "요청에 실패했습니다."
  }
}

---

오류 코드

오류 코드	분류	설명
invalid_grant	OAuth	유효하지 않거나 만료된 인가 코드 또는 토큰
invalid_scope	OAuth	허용되지 않은 scope
INTERNAL_ERROR	서버	내부 서버 오류
USER_KEY_NOT_FOUND	비즈니스	요청한 userKey에 해당하는 유저 없음
USER_NOT_FOUND	비즈니스	토스 유저 정보를 찾을 수 없음
BAD_REQUEST_RETRIEVE_CERT_RESULT_EXCEEDED_LIMIT	비즈니스	DI 포함 조회 횟수 초과 → without-di 엔드포인트 사용
BAD_REQUEST_NOT_ALLOWED_SCOPE	비즈니스	연결 끊기 scope가 설정되지 않은 Client
INVALID_PARAMETER	요청	요청 파라미터 오류