Auth API

카카오 OAuth2 기반 로그인 및 JWT 토큰 관리 엔드포인트입니다.

엔드포인트 목록

메서드	경로	설명	인증
GET	/api/auth/kakao	카카오 로그인 페이지로 리다이렉트 (302)	불필요
POST	/api/auth/kakao/token	인가 코드 → AT/RT 발급	불필요
POST	/api/auth/refresh	Access Token 갱신 (Rotation)	불필요
POST	/api/auth/logout	로그아웃 (RT 폐기)	필요

---

GET /api/auth/kakao

카카오 인가 서버로 302 리다이렉트합니다. 브라우저가 직접 호출합니다.

Response: 302 Redirect → kauth.kakao.com/oauth/authorize?...

---

POST /api/auth/kakao/token

Next.js BFF가 인가 코드를 받아 이 엔드포인트를 호출합니다.

처리 흐름:

1. 인가 코드 → 카카오 액세스 토큰 교환
2. 카카오 사용자 정보 조회
3. 신규 사용자: users 자동 생성 / 재방문: 기존 계정 조회
4. 탈퇴 유예(30일 내) 재방문: 계정 자동 복구
5. JWT(AT + RT) 발급 후 반환

에러:

상황	HTTP	에러 코드
인가 코드 만료/위조	400	INVALID_OAUTH_CODE
카카오 계정 접근 거부	401	OAUTH_PROVIDER_ERROR
카카오 API 장애	502	EXTERNAL_API_ERROR
익명화 완료 사용자	401	DELETED_USER

---

POST /api/auth/refresh

만료된 Access Token을 Refresh Token으로 갱신합니다. Refresh Token Rotation 방식으로 RT도 함께 재발급됩니다.

Request Header:

X-Refresh-Token: {refreshToken}

에러:

상황	HTTP	에러 코드
RT 만료 (14일 초과)	401	REFRESH_TOKEN_EXPIRED
RT 유효하지 않음	401	INVALID_TOKEN

---

POST /api/auth/logout

Refresh Token을 저장소에서 삭제합니다.

Request Header:

Authorization: Bearer {accessToken}
X-Refresh-Token: {refreshToken}

Response: 204 No Content

---

JWT 스펙

항목	값
Access Token 만료	1시간
Refresh Token 만료	14일
서명 알고리즘	HS256
클레임	userId, role, accountStatus

accountStatus가 PENDING_DELETION이면 탈퇴 유예 상태입니다. 복구 엔드포인트 외 모든 API 접근이 차단됩니다.