본문으로 건너뛰기
버전: 개발 버전 (최신)

계정 탈퇴 API (v2)

인증된 사용자가 자발적으로 탈퇴하는 v2 endpoint. 단일 DELETE /v2/auth/users/me 한 번으로 끝나며, 사용자 상태를 비활성으로 전환하는 Soft Delete(데이터 즉시 삭제 없음)다. 신원은 액세스 토큰 payload(userId)로 확정하므로 요청 본문이 없다.

인증 정책 (v2 공통)
  • 인증 채널은 Authorization: Bearer <accessToken> 한 줄.
  • 요청 본문이 없어 검증 단계가 없다 — 400 VALIDATION_ERROR 는 발생하지 않는다.
  • 마스터 문서: Auth 도메인 endpoints (계정 비활성화).
Soft Delete vs Hard Delete

이 endpoint 는 사용자 상태를 비활성으로 바꾸는 Soft Delete 다. 데이터베이스에서 데이터를 영구 삭제하는 개발용 Hard Delete 는 별도 API(사용자 데이터 완전 삭제)를 참조한다.

0. 호출 순서​

#APIAuthorizationbody 핵심응답에서 추출할 값
0(사전) 로그인으로 access token 확보 — eID 로그인 · Native 2FA 로그인——accessToken
1DELETE /v2/auth/users/me ⭐Bearer <accessToken>없음{ userId, deletedAt }

탈퇴는 활성 사용자가 자기 access token 으로 호출하는 단일 게이트다 — 사전 단계(App Token / Email OTP / AppCheck)는 필요 없다.

1. DELETE /v2/auth/users/me ⭐​

인증된 사용자를 탈퇴 처리(DeactivateUserCommand)한다. JwtAuthGuard 가 토큰을 검증하고 payload 의 userId 로 신원을 확정한 뒤 UserAuthService.withdraw(userId) 를 호출한다. 데이터는 즉시 삭제되지 않고 비활성 상태로 전환된다.

  • Path: DELETE /v2/auth/users/me
  • 인증: Access Token 필요 (JwtAuthGuard)
  • 🔗 라이브 명세 (Swagger UI): dev

Request​

HeaderValue
AuthorizationBearer <accessToken>

요청 본문 없음. 신원은 액세스 토큰 payload(userId)로 확정한다.

Response 200 OK​

{
  "userId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "deletedAt": 1678886400000
}
필드타입필수설명
userIdstringYes탈퇴 처리된 사용자 ID.
deletedAtnumberYes탈퇴 처리 시각 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64).

DB 영향​

  • 사용자 상태가 비활성으로 전환된다 (Soft Delete — 데이터 즉시 삭제 없음).
  • 탈퇴 후에는 해당 토큰으로 더 이상 인증할 수 없다.

Errors​

HTTPcodemessage발생 조건
4011000Authentication token not foundBearer 토큰 헤더 누락 (JwtAuthGuard)
4011000Invalid or expired token토큰 검증 실패 — 무효/만료 (JwtAuthGuard)
4011000User not authenticated토큰 payload 에 userId 없음 (컨트롤러)
4094011CONFLICT이미 탈퇴 처리된 사용자 (DeactivateUserCommand BadRequest → CONFLICT 매핑)
5002000SERVER_ERRORBadRequest 외 모든 오류 — 사용자 상태 미존재(NotFound) 포함 (catch-all)

중복 탈퇴 요청은 409 Conflict(detail: "이미 처리되었습니다.")로 거부된다. 사용자 상태를 찾을 수 없는 경우(NotFound)는 catch-all 에서 500 SERVER_ERROR 로 매핑된다.

다음 단계​