비밀번호 변경 API

로그인된 사용자의 비밀번호를 새로운 비밀번호로 변경합니다.

• HTTP Method: PATCH
• Path: /de/v1/auth/password
• 인증:
  • 로그인 전: App Token 필요 (Authorization: Bearer {appToken})
  • 로그인 후: JWT Token 필요 (Authorization: Bearer {accessToken})

Headers

Header	Type	Description	Required
Authorization	string	Bearer {appToken} or Bearer {accessToken} 형식	Yes
Content-Type	application/json	요청 본문 형식을 지정합니다.	Yes
Accept-Language	de-DE, en-US, ko-KR	오류 메시지의 언어를 지정합니다. 지역 코드를 포함한 형식(예: de-DE, en-US, ko-KR)만 지원합니다.	No

Request Body

{
  "email": "user@example.com",
  "verificationId": "verification-id-uuid-123",
  "newPasswordHash": "hashed-password-string"
}

필드	타입	설명	필수
email	string	사용자 이메일 주소	Yes
verificationId	string	이메일 인증 ID	Yes
newPasswordHash	string	새로운 비밀번호 (해시된 형태)	Yes

Responses

HTTP Status Code	설명	Error Code(s)
200 OK	비밀번호 변경 성공	-
400 Bad Request	잘못된 요청 데이터	2011(Device Id가 없는 경우), 2008(로그인 전 이메일 인증 실패), 2090(현재 비밀번호 해시와 동일한 비밀번호 해시인 경우), 2092(로그인 후 비밀번호 인증 실패)
401 Unauthorized	인증 실패 (유효하지 않은 토큰)	2051
404 Not Found	사용자를 찾을 수 없음	7002(이메일에 해당하는 사용자가 없는 경우)
500 Internal Server Error	서버 내부 오류	-

200 OK - 비밀번호 변경 성공

비밀번호가 성공적으로 변경된 경우 반환됩니다.

{
  "success": true
}

필드	타입	설명	필수
success	boolean	비밀번호 변경 성공 여부	Yes

401 Unauthorized - 인증 실패

APP 토큰/JWT 토큰이 유효하지 않거나 사용자 인증에 실패한 경우 반환됩니다.

{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다."
}

필드	타입	설명	필수
code	number	애플리케이션 오류 코드 (2051)	No
message	string	오류 메시지 코드	Yes
detail	string	사용자 친화적인 오류 설명	No

404 Not Found - 사용자를 찾을 수 없음

dto 의 email 에 해당하는 사용자가 존재하지 않는 경우 반환됩니다.

{
  "code": 7002,
  "message": "USER_NOT_FOUND",
  "detail": "사용자를 찾을 수 없습니다."
}

필드	타입	설명	필수
code	number	애플리케이션 오류 코드 (7002)	Yes
message	string	오류 메시지 코드	Yes
detail	string	사용자 친화적인 오류 설명	Yes

400 Bad Request - 잘못된 요청 데이터

요청 본문의 유효성 검증에 실패하거나 필수 데이터가 누락된 경우 반환됩니다.

Device Id가 없는 경우:

{
  "code": 2011,
  "message": "INVALID_DEVICE_ID",
  "detail": "디바이스 ID가 유효하지 않습니다"
}

이메일 인증 실패:

{
  "code": 2008,
  "message": "EMAIL_NOT_VERIFIED",
  "detail": "이메일이 인증되지 않았습니다"
}

비밀번호 인증 실패:

{
  "code": 2092,
  "message": "PASSWORD_NOT_VERIFIED",
  "detail": "비밀번호 인증이 완료되지 않았습니다"
}

현재 비밀번호와 동일한 경우:

{
  "code": 2090,
  "message": "PASSWORD_ALREADY_USED",
  "detail": "현재 비밀번호 해시와 동일합니다"
}

설명

• 이 API는 로그인된 사용자가 자신의 비밀번호를 변경할 때 사용됩니다.
• 로그인 전일 경우 유효한 appToken이 Authorization 헤더에 Bearer 토큰으로 포함되어야 합니다.
• 로그인 후일 경우 유효한 accessToken이 Authorization 헤더에 Bearer 토큰으로 포함되어야 합니다.
• newPasswordHash는 클라이언트에서 미리 해시 처리된 새로운 비밀번호를 전송해야 합니다.
• 비밀번호 변경 과정 (로그인 전):
  1. APP 토큰에서 Device Id 추출 및 검증
  2. VerificationId 검증 (이메일 검증 API를 통해 얻은 Verification Id를 사용합니다.)
  3. 사용자 존재 여부 확인
  4. 새 비밀번호 해시로 사용자 비밀번호 업데이트
• 비밀번호 변경 과정 (로그인 후):
  1. JWT 토큰에서 User Id 추출 및 검증
  2. VerificationId 검증 (비밀번호 확인 API를 통해 얻은 Verification Id를 사용합니다.)
  3. 사용자 존재 여부 확인
  4. 새 비밀번호 해시로 사용자 비밀번호 업데이트
• 성공 시 success: true가 반환됩니다.

오류 참조

• 일반적인 인증/인가 관련 오류 코드(2000번대)는 Auth 도메인 오류 코드를 참조하세요.

공통 오류 응답 형식

모든 오류 응답은 다음과 같은 공통 형식을 따릅니다:

{
  "code": 2000,
  "message": "ERROR_CODE_NAME",
  "detail": "사용자 친화적 오류 메시지"
}

필드	타입	필수	설명
code	number	Y	애플리케이션 오류 코드
message	string	Y	오류 메시지
detail	string	N	상세 설명

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-09-17	AI Assistant	최초 문서 작성