Skip to content

Reset Password

Method

REST method is adopted.

HTTP Method

POST: Execute password reset

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

Execute Password Reset

URI

POST /v1/auth/reset_password

Request Body

The request body is JSON.

{
  "email": "user@example.com",
  "code": "123456",
  "newPassword": "NewSecurePassword123!"
}

Request Parameters

Name Type Required Description
email string Required Email address
code string Required Confirmation code (6 digits)
newPassword string Required New password (minimum 8 characters)

Response

The response is JSON.

{
  "message": "Password reset successful",
  "sessionsRevoked": 3
}

Response Fields

Name Type Description
message string Success message
sessionsRevoked number Number of revoked sessions

Authentication

This endpoint does not require authentication.

Error Handling

The status codes for error handling are as follows.

Description Status Code Status Name
Invalid code or weak password 400 Bad Request
User not found 404 Not Found
Internal server error 500 Internal Server Error

Processing Flow

  1. Extract email, code, and newPassword from request body
  2. Validate the code with AWS Cognito
  3. Update password in Cognito
  4. Invalidate all existing user sessions for security
  5. Return success with the number of invalidated sessions

Detailed Flowchart

flowchart TD
    Start([POST /v1/auth/reset_password]) --> ValidateInput[Input Validation]
    ValidateInput --> ValidEmail{email validation}
    ValidEmail -->|NG| Err400[400 Bad Request]
    ValidEmail -->|OK| ValidCode{code validation<br/>6 digits}
    ValidCode -->|NG| Err400
    ValidCode -->|OK| ValidPass{password validation<br/>min 8 chars}
    ValidPass -->|NG| Err400
    ValidPass -->|OK| Cognito

    Cognito[AWS Cognito<br/>confirmForgotPassword] --> CognitoOK{Successful?}
    CognitoOK -->|NG| Err400
    CognitoOK -->|OK| FindUser[Find User<br/>cognitoSub]

    FindUser --> UserExists{Exists?}
    UserExists -->|No| Err404[404 Not Found]
    UserExists -->|Yes| RevokeSessions[Revoke Sessions<br/>Set deletedAt]

    RevokeSessions --> CountRevoked[Count Revoked]
    CountRevoked --> Success[200 OK<br/>sessionsRevoked]

Security

  • All user sessions are invalidated after password reset
  • Cognito validates password strength
  • Confirmation code can only be used once
  • Failed attempts are logged