Skip to content

Forgot Password

Method

REST method is adopted.

HTTP Method

POST: Password reset request

Naming Convention

To unify the naming of query parameters and nodes and improve readability, snake_case is used for URIs and JSON nodes in requests.

Request and Response

Headers

Meta information is set in HTTP headers, not in the response body.

Request Headers

  • Content-Type
  • Accept
  • Accept-language

Response Headers

  • Content-Type

Password Reset Request

URI

POST /v1/auth/forgot_password

Request Body

The request body is JSON.

{
  "email": "user@example.com"
}

Request Parameters

Name Type Required Description
email string Required Email address (valid email format)

Response

The response is JSON.

{
  "message": "Password reset code sent",
  "codeDeliveryDestination": "u***@example.com",
  "codeDeliveryMedium": "EMAIL"
}

Response Fields

Name Type Description
message string Success message
codeDeliveryDestination string Code delivery destination (masked)
codeDeliveryMedium string Delivery method (EMAIL)

Authentication

This endpoint does not require authentication.

Error Handling

The status codes for error handling are as follows.

Description Status Code Status Name
Invalid email format 400 Bad Request
Internal server error 500 Internal Server Error

Processing Flow

  1. Extract email from request body
  2. Request password reset code from AWS Cognito
  3. Cognito sends a confirmation code to the user's email address
  4. Return delivery destination information

Detailed Flowchart

flowchart TD
    Start([POST /v1/auth/forgot_password]) --> ValidateInput[Input Validation]
    ValidateInput --> ValidEmail{email validation}
    ValidEmail -->|NG| Err400[400 Bad Request]
    ValidEmail -->|OK| Cognito[AWS Cognito<br/>forgotPassword]

    Cognito --> CognitoOK{Successful?}
    CognitoOK -->|NG| HandleError[Error Handling]
    HandleError --> Success
    CognitoOK -->|OK| Success[200 OK<br/>code delivery info]

    Note1[User enumeration prevention:<br/>Returns success even for non-existent emails]

Security

  • Returns success even if email address does not exist (prevents user enumeration)
  • Rate limiting prevents abuse
  • Confirmation codes expire after a configured time