이메일 인증 API
개요
이메일 인증 API는 사용자 회원가입, 비밀번호 재설정 또는 특정 기능 사용 전에 이메일 주소의 유효성을 검증하기 위해 인증 코드를 발송하는 기능을 제공합니다. 사용자 선호 언어(독일어, 영어, 한국어)에 따라 이메일 인증 코드가 발송됩니다.
이메일 인증 타입
인증 목적에 따라 다음과 같은 이메일 인증 타입이 제공됩니다:
REGISTRATION: 회원가입 과정에서 사용되는 이메일 인증LOGIN: 로그인 과정에서 사용되는 이메일 인증PASSWORD_RESET: 비밀번호 재설정 과정에서 사용되는 이메일 인증
각 요청에서 type 필드를 통해 인증 목적을 명시해야 하며, 이에 따라 적절한 인증 프로세스가 적용됩니다.
이메일 인증 코드 발송
사용자 이메일로 인증 코드를 발송합니다. 인증 목적에 따라 type 필드를 지정하여 사용합니다.
- HTTP Method:
POST - Path:
/de/v1/auth/email/verification-code - 인증: App Token 필요 (Authorization: Bearer
{appToken})
Headers
| Header | Type | Description | Required |
|---|---|---|---|
Content-Type | application/json | 요청 본문 형식을 지정합니다. | Yes |
Authorization | Bearer {appToken} | 앱 인증을 통해 발급받은 토큰입니다. | Yes |
Accept-Language | Language Code | 사용자 선호 언어를 지정합니다. 지역 코드를 포함한 형식만 지원합니다. | No |
Request Body
{
"email": "user@example.com",
"type": "REGISTRATION"
}
| 필드 | 타입 | 설명 | 필수 |
|---|---|---|---|
email | string | 인증 코드를 발송할 사용자 이메일 주소 | Yes |
type | string | 이메일 인증 타입 (REGISTRATION, LOGIN, PASSWORD_RESET) (EmailVerificationType 참조) | Yes |
Responses
| HTTP Status Code | 설명 | Error Code(s) |
|---|---|---|
200 OK | 성공 | - |
400 Bad Request | 잘못된 요청 (예: 유효하지 않은 이메일 형식) | 2023 |
401 Unauthorized | 인증 실패 (예: 유효하지 않은 앱 토큰) | 2051 |
409 Conflict | 이미 가입된 이메일 (type이 REGISTRATION인 경우) | 2024 |
422 Unprocessable Entity | 가입되지 않은 이메일 (type이 PASSWORD_RESET 또는 LOGIN인 경우) | 2027 |
429 Too Many Requests | 요청 제한 초과 | 2040 |
500 Internal Server Error | 서버 내부 오류 (예: Redis 저장 실패, 이메일 발송 실패) | 2010 |
200 OK - 성공
{
"success": true,
"email": "user@example.com",
"expiresIn": 300,
"requestId": "req_123",
"type": "REGISTRATION"
}
| 필드 | 타입 | 설명 | 필수 |
|---|---|---|---|
success | boolean | 요청 성공 여부 | Yes |
email | string | 코드가 발송된 이메일 주소 | Yes |
expiresIn | number | 발송된 인증 코드의 유효 시간 (초) | Yes |
requestId | string | 요청 추적 ID (코드 확인 시 필요) | Yes |
type | string | 이메일 인증 타입 (REGISTRATION, LOGIN, PASSWORD_RESET) (EmailVerificationType 참조) | Yes |
400 Bad Request - 잘못된 요청 (예: 유효하지 않은 이메일 형식)
{
"code": 2023,
"message": "INVALID_EMAIL_FORMAT",
"detail": "유효한 이메일 주소를 입력해주세요."
}
401 Unauthorized - 인증 실패 (예: 유효하지 않은 앱 토큰)
{
"code": 2051,
"message": "INVALID_TOKEN",
"detail": "토큰이 유효하지 않습니다"
}
409 Conflict - 이미 가입된 이메일 (type이 REGISTRATION인 경우)
{
"code": 2024,
"message": "DUPLICATE_EMAIL",
"detail": "이미 가입된 이메일입니다."
}
422 Unprocessable Entity - 가입되지 않은 이메일 (type이 PASSWORD_RESET, LOGIN인 경우)
{
"code": 2027,
"message": "UNREGISTERED_EMAIL",
"detail": "가입되지 않은 이메일입니다",
"metadata": {
"email": "test@weltcorp.com"
}
}
429 Too Many Requests - 요청 제한 초과
{
"code": 2040,
"message": "RATE_LIMIT_EXCEEDED",
"detail": "요청 횟수가 제한을 초과했습니다. 잠시 후 다시 시도해주세요.",
"metadata": {
"remainingLockoutSeconds": 599 // 잠금 해제까지 남은 시간(초)
}
}
참고: 코드 발송 API와 마찬가지로, 코드 확인 API에도 과도한 요청을 방지하기 위한 Rate Limiting(예: IP 기준 제한)이 적용될 수 있습니다.
500 Internal Server Error - 서버 내부 오류 (예: Redis 저장 실패, 이메일 발송 실패)
{
"code": 2010, // 또는 EMAIL_SEND_FAILED
"message": "SERVER_ERROR",
"detail": "서버 내부 오류가 발생했습니다. 이메일 발송에 실패했을 수 있습니다."
}
설명
- 이 API는 주로 회원가입, 로그인, 비밀번호 재설정 등 다양한 인증 과정에서 사용자의 이메일 소유권을 확인하기 위해 사용됩니다.
- 성공적으로 호출되면 지정된 이메일 주소로 6자리 숫자 인증 코드가 발송됩니다.
- 발송된 코드는
expiresIn에 명시된 시간 동안 유효합니다. - 사용자는 이 코드를 사용하여 이메일 인증 코드 확인 API (
POST /auth/email/verify)를 호출해야 합니다. - Type별 특성:
REGISTRATION: 신규 사용자 등록 시 사용됩니다. 이미 가입된 이메일인 경우DUPLICATE_EMAIL오류가 발생합니다.LOGIN: 로그인 시 추가 보안 조치로 사용됩니다. 가입되지 않은 이메일인 경우UNREGISTERED_EMAIL오류가 발생합니다.PASSWORD_RESET: 비밀번호 재설정 시 사용됩니다. 가입되지 않은 이메일인 경우UNREGISTERED_EMAIL오류가 발생합니다.
- Rate Limiting: 동일 이메일 또는 IP 주소에서 단시간 내 과도한 요청을 방지하기 위한 제한이 적용됩니다. 제한 초과 시
429 Too Many Requests오류가 발생하며, 일정 시간 동안 요청이 차단될 수 있습니다. - 다국어 지원: 이메일 인증 코드는 사용자의 선호 언어로 발송됩니다. 언어는
Accept-Language헤더를 통해 지정할 수 있으며, Language Code 형식만 지원합니다. 현재 지원하는 언어는 독일어(de-DE), 영어(en-US), 한국어(ko-KR)입니다. 헤더가 없거나 지원하지 않는 언어인 경우 기본 언어(독일어)로 발송됩니다.
이메일 인증 코드 확인
사용자가 이메일로 받은 인증 코드를 확인하여 이메일 주소의 유효성을 검증합니다.
- HTTP Method:
POST - Path:
/de/v1/auth/email/verify - 인증: 앱 토큰 (
appToken) 필요
Headers
| Header | Type | Description | Required |
|---|---|---|---|
Content-Type | application/json | 요청 본문 형식을 지정합니다. | Yes |
Authorization | Bearer {appToken} | 앱 인증을 통해 발급받은 토큰입니다. | Yes |
Accept-Language | Language Code | 응답 메시지의 언어를 지정합니다. 지역 코드를 포함한 형식만 지원합니다. | No |
Request Body
{
"email": "user@example.com",
"code": "123456",
"requestId": "req_123",
"type": "REGISTRATION"
}
| 필드 | 타입 | 설명 | 필수 |
|---|---|---|---|
email | string | 인증 코드를 받은 사용자 이메일 주소 | Yes |
code | string | 이메일로 받은 6자리 인증 코드 | Yes |
requestId | string | 코드 발송 요청 시 받은 요청 ID | Yes |
type | string | 이메일 인증 타입 (REGISTRATION, LOGIN, PASSWORD_RESET) (EmailVerificationType 참조, 유효한 경우에만 반환) | Yes |
Responses
| HTTP Status Code | 설명 | Error Code(s) |
|---|---|---|
400 Bad Request | 잘못된 요청 (예: 유효하지 않은 인증 코드, 코드 만료 등) | 2017, 2014 |
401 Unauthorized | 인증 실패 (예: 유효하지 않은 앱 토큰) | 2051 |
409 Conflict | 리소스 충돌 (예: 이미 인증 완료된 이메일) | 2026 |
429 Too Many Requests | 요청 제한 초과 (예: 시도 횟수 초과, 계정 잠김) | 2018, 2040 |
500 Internal Server Error | 서버 내부 오류 | 2000 |
200 OK - 인증 코드 검증 결과. 본문의 valid 필드를 확인하세요.
The response indicates whether the email verification was successful.
성공 (검증 성공):
{
"valid": true,
"verificationId": "ver_abc123xyz",
"verifiedAt": 1711011900000,
"expiresAt": 1711013700000,
"email": "user@example.com",
"type": "REGISTRATION"
}
| 필드 | 타입 | 설명 | 필수 |
|---|---|---|---|
valid | boolean | 인증 유효 여부 | Yes |
verificationId | string | 인증 ID (유효한 경우에만 반환) | No |
verifiedAt | number | 인증 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64, 유효한 경우에만 반환) | No |
expiresAt | number | 인증 만료 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64, 유효한 경우에만 반환) | No |
email | string | 이메일 주소 (유효한 경우에만 반환) | No |
type | string | 이메일 인증 타입 (REGISTRATION, LOGIN, PASSWORD_RESET) (EmailVerificationType 참조, 유효한 경우에만 반환) | No |
400 Bad Request - 잘못된 요청
예시: 제공된 인증 코드 또는 요청 ID가 유효하지 않음 (INVALID_VERIFICATION_CODE - 2017)
사용자가 입력한 인증 코드 또는 코드 발송 시 전달받은 요청 ID(requestId)가 서버에 저장된 값과 일치하지 않을 때 발생합니다.
이 오류는 아직 최대 시도 횟수에 도달하지 않았음을 의미합니다.
{
"code": 2017,
"message": "INVALID_VERIFICATION_CODE",
"detail": "제공된 인증 코드가 유효하지 않거나 요청 ID가 일치하지 않습니다.",
"metadata": {
"remainingAttempts": 4
}
}
예시: 인증 코드 만료 (VERIFICATION_CODE_EXPIRED - 2014)
인증 코드가 존재하지 않거나 (잘못된 이메일 또는 requestId) 유효 시간이 초과되었을 때 발생합니다.
{
"code": 2014,
"message": "VERIFICATION_CODE_EXPIRED",
"detail": "인증 코드가 만료되었거나 존재하지 않습니다."
}
401 Unauthorized - 인증 실패
예시: 유효하지 않은 앱 토큰 (INVALID_APP_TOKEN - 2051)
요청 헤더에 포함된 앱 토큰(appToken)이 유효하지 않거나 누락되었을 때 발생합니다.
{
"code": 2051,
"message": "INVALID_TOKEN",
"detail": "토큰이 유효하지 않습니다"
}
409 Conflict - 리소스 충돌
예시: 이미 인증 완료됨 (EMAIL_VERIFICATION_ALREADY_COMPLETED - 2026)
해당 이메일 주소는 이미 인증 절차를 성공적으로 완료했으며, 현재 유효한 인증 상태일 때 발생합니다.
{
"code": 2026,
"message": "EMAIL_VERIFICATION_ALREADY_COMPLETED",
"detail": "이미 인증이 완료된 이메일입니다."
}
429 Too Many Requests - 요청 제한 초과
예시: 시도 횟수 초과 (VERIFICATION_ATTEMPTS_EXCEEDED - 2018)
잘못된 인증 코드를 반복적으로 제출하여 허용된 최대 시도 횟수를 초과했을 때 발생합니다. 이 경우, 해당 이메일의 인증 시도가 일정 시간 동안 잠금 처리됩니다.
{
"code": 2018,
"message": "VERIFICATION_ATTEMPTS_EXCEEDED",
"detail": "인증 시도 횟수를 초과했습니다. 계정이 일시적으로 잠금 처리됩니다.",
"metadata": {
"remainingLockoutSeconds": 3600
}
}
예시: 일반 요청 제한 초과 (RATE_LIMIT_EXCEEDED - 2040)
계정이 이미 잠겨 있는 상태에서 인증을 시도하거나, API의 일반적인 요청 속도 제한(Rate Limiting) 정책을 위반했을 때 발생할 수 있습니다.
{
"code": 2040,
"message": "RATE_LIMIT_EXCEEDED",
"detail": "요청 횟수가 제한을 초과했습니다. 잠시 후 다시 시도해주세요.",
"metadata": {
"remainingLockoutSeconds": 599
}
}
참고:
metadata필드는 계정 잠금 상황에서 주로 포함됩니다. 일반적인 API 속도 제한의 경우metadata가 없을 수 있습니다.
500 Internal Server Error - 서버 내부 오류
예시: 일반 서버 오류 (SERVER_ERROR - 2000)
서버 내부 로직 처리 중 예상치 못한 문제가 발생했을 때 반환됩니다 (예: 데이터베이스 오류, Redis 파싱 오류 등).
{
"code": 2000,
"message": "SERVER_ERROR",
"detail": "서버 내부 오류가 발생했습니다."
}
설명
- 이 API는 이메일 인증 코드 발송 API를 통해 사용자가 전달받은 인증 코드를 검증합니다.
valid필드가true이면 인증에 성공한 것이며,verificationId,verifiedAt,expiresAt,email,type등의 추가 정보가 함께 반환될 수 있습니다.
변경 이력
| 버전 | 날짜 | 작성자 | 변경 내용 |
|---|---|---|---|
| 0.1.0 | 2025-05-28 | elizabeth@weltcorp.com | 최초 문서 작성 |
| 0.2.0 | 2025-06-12 | elizabeth@weltcorp.com | 오류 코드 표준화 (2002 → 2051 INVALID_TOKEN) |