이 문서는 https://in.passv.co.kr 운영 기준으로 카카오 로그인을 붙이는 초안 매뉴얼이다.
2026-03-27 기준 PASSV 운영 baseline과 Kakao Developers 공식 문서를 함께 반영했다. 아직 실제 운영 화면 캡처는 붙이지 않았고, 설정 순서와 운영 값 위주로 먼저 정리했다.
이 초안에서 끝내야 하는 일은 아래 4가지다.
카카오로 시작하기 흐름이 시작되는지 확인한다.| 항목 | 값 |
|---|---|
| 운영 주소 | https://in.passv.co.kr |
| 로그인 화면 | https://in.passv.co.kr/login |
| 카카오 로그인 시작 경로 | https://in.passv.co.kr/api/auth/kakao/start |
| 카카오 로그인 콜백 URI | https://in.passv.co.kr/api/auth/kakao/callback |
| 프론트 변수 | VITE_KAKAO_REST_API_KEY |
| 백엔드 변수 1 | KAKAO_REST_API_KEY |
| 백엔드 변수 2 | KAKAO_CLIENT_SECRET |
| 백엔드 변수 3 | KAKAO_REDIRECT_URI |
| 현재 authorize scope | account_email |
| 현재 꼭 켜야 하는 동의항목 | 카카오계정(이메일) |
중요한 점은 아래 4개다.
redirect_uri는 Kakao Developers에 등록한 값과 요청에 쓰는 값이 글자 하나까지 같아야 한다.GET /api/auth/kakao/start에서 scope=account_email만 요청한다.동의항목에서 카카오계정(이메일)이 비활성화돼 있으면 KOE205 invalid_scope가 날 수 있다.Client Secret은 백엔드에서만 사용한다.https://developers.kakao.com/에 로그인한다.앱 > 일반 > 앱 기본 정보로 이동한다.앱 이름은 실제 사용자에게 보일 서비스명으로 확인한다.회사명은 실제 운영 주체명으로 입력돼 있는지 확인한다.앱 대표 도메인은 현재 운영 도메인 정책과 맞는지 확인한다.PASSV다.https://in.passv.co.kr
https://in.passv.co.kr에서 로그인 버튼을 노출한다.카카오 로그인 > 사용 설정으로 이동한다.상태를 ON으로 바꾼다.상태가 OFF이면 로그인 요청 시 KOE004 에러가 발생한다.앱 > 플랫폼 키 > REST API 키 > 리다이렉트 URI로 이동한다.https://in.passv.co.kr/api/auth/kakao/callback
redirect_uri가 다르면 KOE006 에러가 발생한다.https://in.passv.co.kr/api/auth/kakao/callback이다.카카오 로그인 > 동의항목으로 이동한다.카카오계정(이메일) 항목을 찾는다.선택 동의 또는 필수 동의로 저장한다.scope로 account_email만 요청한다.필수 동의로 강제하려면 비즈 앱 전환과 관련 심사가 필요할 수 있다.선택 동의라도 켜서 흐름이 막히지 않게 맞추는 편이 실무적으로 안전하다.앱 > 플랫폼 키 > REST API 키 > 클라이언트 시크릿으로 이동한다.KAKAO_CLIENT_SECRET을 사용한다.카카오 앱에서 확인한 값을 아래처럼 넣으면 된다.
| 위치 | 변수명 | 넣는 값 |
|---|---|---|
| 프론트 운영 변수 | VITE_KAKAO_REST_API_KEY |
Kakao Developers의 REST API 키 |
| 백엔드 운영 변수 | KAKAO_REST_API_KEY |
같은 REST API 키 |
| 백엔드 운영 변수 | KAKAO_CLIENT_SECRET |
Kakao Developers의 Client Secret |
| 백엔드 운영 변수 | KAKAO_REDIRECT_URI |
https://in.passv.co.kr/api/auth/kakao/callback |
| 구분 | 파일 | 의미 |
|---|---|---|
| 프론트 예시 변수 | client/mobile/.env.example |
VITE_KAKAO_REST_API_KEY 자리 |
| 백엔드 예시 변수 | server/.env.example |
KAKAO_REST_API_KEY, KAKAO_CLIENT_SECRET, KAKAO_REDIRECT_URI 자리 |
| 프론트 시작 URL | client/mobile/src/mobile-auth/kakaoIdentity.ts |
/api/auth/kakao/start로 진입 |
| 운영 상태 기록 | passv/sdd/05_operate/02_delivery_status/service_status.md |
2026-03-27 기준 운영 Redirect URI와 scope 기록 |
KAKAO_REDIRECT_URI는 현재 운영에서 https://in.passv.co.kr/api/auth/kakao/callback로 고정해 맞추는 편이 안전하다.https://in.passv.co.kr/login으로 이동한다.카카오로 시작하기 버튼이 보이는지 확인한다.https://in.passv.co.kr/api/auth/kakao/start로 시작되는 흐름이 열리는지 확인한다.redirect_uri와 scope를 먼저 확인한다.GET https://in.passv.co.kr/api/auth/kakao/start는 HTTP 307과 함께 Kakao authorize URL을 반환한다.redirect_uri=https://in.passv.co.kr/api/auth/kakao/callback와 scope=account_email이다.ON으로 켰다.https://in.passv.co.kr를 기준으로 웹 표면을 정리했다.https://in.passv.co.kr/api/auth/kakao/callback를 등록했다.카카오계정(이메일) 동의항목을 켰다.REST API 키를 VITE_KAKAO_REST_API_KEY와 KAKAO_REST_API_KEY에 같은 값으로 넣었다.Client Secret을 KAKAO_CLIENT_SECRET에 넣었다.KAKAO_REDIRECT_URI를 운영 콜백 URI와 같게 맞췄다.카카오로 시작하기 버튼을 눌러 흐름이 시작되는지 확인했다.