Skip to content

Reset Password

Method

REST method is adopted.

HTTP Method

POST: Password reset confirmation

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

Reset Password

URI

/api/v1/auth/reset_password

Request Body

Request body is JSON. 

{
  "email": "admin@example.com",
  "code": "123456",
  "new_password": "NewSecurePassword123"
}

Validation Rules

Field Rule
email Required. Must be a valid email format.
code Required. 6-digit verification code received via email.
new_password Required. Minimum 8 characters, at least 1 uppercase, 1 lowercase, and 1 number.

Response (200 OK)

Response is JSON. 

{
  "message": "Password has been reset successfully",
  "sessions_revoked": 3
}

Note: sessions_revoked indicates the number of active sessions that were invalidated as a security measure after the password reset.

Authentication

This endpoint does not require authentication. The verification code from the forgot password flow serves as the authentication mechanism.

Exception Handling

Exception handling status codes are as follows.

Description Status Code Status Name
Invalid request body or validation error 400 Bad Request
Invalid or expired verification code 401 Unauthorized
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
    participant DB as PostgreSQL Database

    Client->>API: POST /api/v1/auth/reset_password
    API->>Validate: Validate email, code, new_password
    Validate-->>API: Validation passed

    API->>Service: resetPassword(email, code, newPassword)
    Service->>Cognito: confirmForgotPassword(email, code, newPassword)

    alt Code Valid
        Cognito-->>Service: Password updated
        Service->>DB: Find all active sessions for admin
        DB-->>Service: Active sessions list
        Service->>DB: Revoke all active sessions
        DB-->>Service: Sessions revoked (count)
        Service-->>API: { message, sessionsRevoked }
        API-->>Client: 200 OK
    else Code Invalid or Expired
        Cognito-->>Service: CodeMismatchException / ExpiredCodeException
        Service-->>API: throw UnauthorizedError
        API-->>Client: 401 Unauthorized
    end

Routes Layer

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

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

Services Layer

This section describes business logic. It confirms the password reset with AWS Cognito using the verification code, updates the password, and revokes all existing sessions for security.

Source: src/services/auth.ts

Repositories Layer

This section describes access to databases and external services. It handles session lookup and batch revocation for the admin user.

Source: src/repositories/

Security

  • All existing sessions are revoked after password reset (forced re-login on all devices)
  • Verification code can only be used once
  • Password strength validated by both Zod schema and Cognito policies
  • Failed attempts are logged for security monitoring