Skip to content

Forgot Password

Method

REST method is adopted.

HTTP Method

POST: Password reset request

Naming Convention

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

Request and Response

Headers

Meta information is set in HTTP headers rather than in the response body.

Request Headers

  • Content-Type: application/json

Response Headers

  • Content-Type: application/json

Forgot Password

URI

/api/v1/auth/forgot_password

Request Body

Request body is JSON. 

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

Validation Rules

Field Rule
email Required. Must be a valid email format.

Response (200 OK)

Response is JSON. 

{
  "message": "Password reset code sent",
  "code_delivery_destination": "a***@example.com",
  "code_delivery_medium": "EMAIL"
}

Note: The response is identical whether the email exists or not. This prevents user enumeration attacks. The code_delivery_destination and code_delivery_medium fields are only present when the email is found.

Authentication

This endpoint does not require authentication.

Exception Handling

Exception handling status codes are as follows.

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

Process Flow

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as Hono Router
    participant Validate as Zod Validation
    participant Service as Auth Service
    participant Cognito as AWS Cognito

    Client->>API: POST /api/v1/auth/forgot_password
    API->>Validate: Validate email
    Validate-->>API: Validation passed

    API->>Service: forgotPassword(email)
    Service->>Cognito: forgotPassword(email)

    alt Email Exists
        Cognito-->>Service: Code sent (delivery details)
        Service-->>API: { message, codeDeliveryDestination, codeDeliveryMedium }
        API-->>Client: 200 OK
    else Email Not Found
        Cognito-->>Service: UserNotFoundException
        Service-->>API: { message: "If the email exists..." }
        API-->>Client: 200 OK (same response format)
    end

Routes Layer

API routing is performed here. Validates the email field using Zod schema, then delegates to the auth service.

Source: src/routes/v1/auth.ts:104

Services Layer

This section describes business logic. It requests a password reset code from AWS Cognito, which sends a verification code to the user's email. The response is timing-safe to prevent user enumeration.

Source: src/services/auth.ts

Repositories Layer

This section describes access to external services. It interacts with AWS Cognito for the forgot password flow.

Source: src/repositories/

Security

  • Returns the same response regardless of whether the email exists (prevents user enumeration)
  • Verification code expires after a configured time
  • Rate limiting handled by API Gateway / Cognito