Returns the health status of the API

Authenticate user with username and password via AWS Cognito. This endpoint handles both regular users and Money Forward bot users with different authentication flows.

Flow Overview:

1. Receives username and password from client
2. Verifies client token (Access-Token)
3. Extracts source IP address from X-Forwarded-For header
4. Checks IP whitelist (ip_whitelist table for the client)
5. Routes to appropriate flow based on IP whitelist status

Flow A: Whitelisted IP (Money Forward Bot)

• IP address is registered in ip_whitelist table for the client
• Checks account lock status in login_lists table
• Bypasses MFA/2FA verification requirements (no phone call verification needed during login)
• Bypasses password-disabled settings (twofa_enabled/passkey checks)
• Password validation is sufficient for authentication
• After successful authentication, checks 2FA settings:
  • If 2FA is enabled (twofa_enabled = TRUE): Returns tokens with session_access_state = 'restricted_access' (MFA verification is bypassed for whitelisted IPs during login, but session state reflects 2FA requirement)
  • If 2FA is not enabled (twofa_enabled = FALSE): Returns tokens with session_access_state = 'full_access'

Flow B: Regular IP (Standard User)

• IP address is not whitelisted
• Checks account lock status in login_lists table
• Checks if passkey authentication is enabled (twofa_enabled = TRUE AND twofa_method = 'passkey')
  • If passkey auth enabled, returns 401 Unauthorized with message "Invalid username or password"
• If password auth allowed, initiates Cognito authentication
• After successful password authentication, checks 2FA settings:
  • If 2FA is enabled (twofa_enabled = TRUE): Returns tokens with session_access_state = 'restricted_access' (user needs to set up 2FA method if not already configured)
  • If 2FA is not enabled (twofa_enabled = FALSE): Returns tokens with session_access_state = 'full_access'
• Phone verification (if 2FA is enabled and method is phone) is handled via separate endpoint /call/start after login

Automatic Migration:

• If user does not exist in Cognito, Cognito automatically triggers User Migration Lambda:
  • Lambda verifies user against Legacy DB (auth_user table)
  • Lambda verifies password hash: SHA1(SECURITY_SALT + password)
  • Lambda returns user attributes to Cognito (email, username, email_verified=true, custom:external_user_id)
  • Cognito automatically creates the user in User Pool (FinalUserStatus=CONFIRMED, MessageAction=SUPPRESS) with custom:external_user_id attribute set
  • Lambda gets cognito_sub from Cognito (AdminGetUser API)
  • Lambda checks if mfa_users record exists (by cognito_username)
  • If record exists: Lambda updates mfa_users record with cognito_sub
  • If record does not exist: Lambda creates mfa_users record with cognito_sub already set
• After successful authentication, system updates mfa_users record with client_id (if NULL)

Username Format:

• Username format is determined by the calling service
• Example: members_api.12345

Session Access State:

• full_access: User has full access to all features immediately
  • Set for whitelisted IPs (Money Forward Bot) when 2FA is not enabled
  • Set for regular users when 2FA is not enabled
• restricted_access: User has limited access until 2FA setup/verification is completed
  • Set for whitelisted IPs (Money Forward Bot) when 2FA is enabled (MFA verification is bypassed for whitelisted IPs during login, but session state reflects 2FA requirement)
  • Set for regular users when 2FA is enabled (user needs to set up 2FA method if not already configured)
  • User must complete 2FA setup/verification (e.g., phone verification via /call/start endpoint if method is phone) to gain full access
  • Restricted access prevents sensitive operations (e.g., fund applications, deposit refunds)

Login Method:

• password: General user login with username and password
• money_forward_bot: Money Forward bot login (whitelisted IP address)

Request password reset for a user. This endpoint initiates the password reset flow by sending a verification code to the user's email address via AWS Cognito.

Flow Overview:

1. Receives Cognito username from the calling service
2. Verifies client token (Access-Token)
3. Queries mfa_users in New DB to get cognito_username
4. Calls AWS Cognito ForgotPassword API to send 6-digit verification code via email

Automatic Migration:

• If user does not exist in Cognito, Cognito automatically triggers User Migration Lambda:
  • Lambda looks up user in Legacy DB (auth_user table)
  • Lambda returns user attributes to Cognito (email, username, email_verified=true, custom:external_user_id)
  • Cognito creates the user in User Pool (FinalUserStatus=CONFIRMED, MessageAction=SUPPRESS) with custom:external_user_id attribute set
  • After Cognito creates user, auth-api checks if mfa_users record exists by cognito_username
  • If record exists: No update needed, skip (cognito_sub will be set when user logs in)
  • If record does not exist: Create new mfa_users record with cognito_username and cognito_sub = NULL (will be set later when user logs in)
• After migration, Cognito sends verification code via email

Username Format:

• Username format is determined by the calling service
• Example: members_api.12345

Verification Code:

• Cognito sends a 6-digit verification code to the user's registered email address
• The code expires after a configured time (typically 15 minutes)
• User must use this code in the confirm-forgot-password endpoint to reset their password

Confirm password reset by verifying the code sent via email and setting a new password in Cognito.

Flow Overview:

1. Receives Cognito username, verification code, and new password from the calling service
2. Verifies client token (Access-Token)
3. Queries mfa_users in New DB to get cognito_username
4. Calls AWS Cognito ConfirmForgotPassword API to verify the code and set the new password
5. If code is valid, Cognito password is updated
6. After successful Cognito update, the calling service is responsible for updating the legacy database password

Username Format:

• Username format is determined by the calling service
• The username must match the format used when the user was registered in Cognito

Password Requirements:

• Must meet Cognito password policy requirements
• Typically: 8-30 characters, mix of uppercase, lowercase, and numbers

Verification Code:

• Must be the 6-digit code received via email from Cognito
• If code is invalid or expired, returns 400 Bad Request with error message

Important:

• Both Cognito and legacy DB passwords should be updated together
• If Cognito update fails, the calling service should NOT update the legacy database password
• User must request a new password reset code if verification fails

Error Responses:

• 400 Bad Request: Returns error message describing the issue (e.g., invalid/expired verification code, invalid password format, user not found, Cognito service error)
• 422 Validation Error: Returns validation errors for request format issues (e.g., missing required fields, invalid format)

Change user's email address in AWS Cognito. This endpoint initiates the email change process by updating the email attribute in Cognito.

Flow Overview:

1. Validates Cognito access token from Authorization header
2. Calls AWS Cognito UpdateUserAttributes API to update email attribute
3. Cognito automatically generates and sends a 6-digit verification code to the new email address
4. Sets email_verified = false until user verifies the code

Important Notes:

• The email in Cognito is changed to the new email immediately, but email_verified = false
• User must verify the email using the verification code sent to the new email address
• The verification code is typically 6 digits and expires after 3-5 minutes
• User must call /email/verify endpoint to complete the email change process
• Legacy database should be updated by the calling service after successful verification

Prerequisites:

• User must be logged in with Cognito authentication (valid access token required)
• User must have migrated to Cognito (have a record in mfa_users table)
• New email address must not be used by any other accounts

Retrieve the current email address and verification status from Cognito for the authenticated user.

Flow Overview:

1. Validates Cognito access token from Authorization header
2. Calls AWS Cognito GetUser API to retrieve user attributes
3. Returns email address and email_verified status

Use Cases:

• Check if email has been verified after change request
• Display current email address and verification status to user
• Determine if user needs to verify email before proceeding

Prerequisites:

• User must be logged in with Cognito authentication (valid access token required)

Verify the email address change by submitting the verification code sent to the new email address.

Flow Overview:

1. Validates Cognito access token from Authorization header
2. Calls AWS Cognito VerifyUserAttribute API to verify the code
3. If code is valid, Cognito sets email_verified = true

Important Notes:

• The verification code is a 6-digit code sent to the new email address
• The code typically expires after 3-5 minutes
• If code is invalid or expired, user can request a new code via /email/resend-verification
• After successful verification, the calling service should update the legacy database (auth_user.email and auth_user.username)
• Legacy database update is handled by the calling service, not auth-api

Prerequisites:

• User must be logged in with Cognito authentication (valid access token required)
• User must have requested email change via /email/change endpoint
• User must have received verification code via email

Resend the verification code to the current email address in Cognito.

Flow Overview:

1. Validates Cognito access token from Authorization header
2. Calls AWS Cognito GetUserAttributeVerificationCode API
3. Cognito generates and sends a new 6-digit verification code to the email address

Important Notes:

• This endpoint sends a new verification code to the email address currently set in Cognito
• The new code replaces any previously sent code
• The code is typically 6 digits and expires after 3-5 minutes
• User should check email spam folder if code is not received

Prerequisites:

• User must be logged in with Cognito authentication (valid access token required)
• User must have requested email change via /email/change endpoint
• Email must not be already verified (should be checked by the calling service before calling this endpoint)

Verify the validity of the current access token.

Flow Overview:

1. Validates Cognito access token from Authorization header
2. Returns success if token is valid

Prerequisites:

• User must be logged in with Cognito authentication (valid access token required)

Refresh the access token using a refresh token to obtain new authentication tokens.

Flow Overview:

1. Verifies client token (Access-Token)
2. Calls AWS Cognito InitiateAuth with REFRESH_TOKEN_AUTH flow
3. Returns new access token, ID token, and token metadata
4. login_method and session_access_state are inherited from the previous login session

Prerequisites:

• Valid refresh token from previous authentication
• Client token (Access-Token) must be valid

Register a new user in AWS Cognito and create MFA user record.

Flow Overview:

1. Verifies client token (Access-Token)
2. Calls AWS Cognito SignUp API with:
   • username (provided by the calling service)
   • password = user's password
   • email attribute set to user's email
   • custom:external_user_id custom attribute set to user's external_user_id
3. Cognito triggers Pre-SignUp Lambda which:
   • Sets AutoConfirmUser = true (user is immediately confirmed)
   • Sets AutoVerifyEmail = true (email is automatically verified)
4. Creates mfa_users record in New DB with:
   • client_id (resolved from verified Access-Token)
   • external_user_id
   • cognito_sub (from Cognito UserSub)
   • cognito_username (the username used in Cognito)
   • twofa_enabled = TRUE (2FA is enabled for new users, requiring setup on first login)
   • twofa_method = NULL (2FA method is not yet configured, user needs to set up 2FA method)

2FA Settings for New Users:

• New users are registered with twofa_enabled = TRUE and twofa_method = NULL
• This ensures that when users first log in, they will have session_access_state = 'restricted_access' and must set up a 2FA method (phone or passkey) to gain full access
• User can configure their preferred 2FA method after first login

Username Format:

• Username format is determined by the calling service
• The username must be unique within the Cognito User Pool
• The username is provided in the request body by the calling service
• Example: members_api.12345

Password Requirements:

• Must meet Cognito password policy requirements
• Typically: 8-30 characters, mix of uppercase, lowercase, and numbers

On success, the user is confirmed in Cognito and ready for subsequent authentication and MFA flows.

Switch user session from current account (User A) to a linked account (User B). This endpoint is called by members-api after validating the relationship between User A and User B.

Flow Overview:

1. Validates access token (middleware) - signature, expiration, issuer to identify the user
2. Validates request format and required fields
3. Checks if User B exists in the new system database (mfa_users)
4. If User B does not exist, performs automatic migration:
   • Generates a random temporary password
   • Creates User B in AWS Cognito using AdminCreateUser with:
     • email_verified = true
     • custom:external_user_id = target_external_user_id
     • MessageAction = SUPPRESS
   • User is created in FORCE_CHANGE_PASSWORD state (AdminCreateUser bypasses PreSignUp Lambda)
   • User is created with custom:external_user_id attribute set
   • Gets cognito_sub using AdminGetUser API
   • Creates mfa_users record with cognito_sub already set
5. Initiates AWS Cognito CUSTOM_AUTH flow with:
   • USERNAME = target_username (cognito username)
   • ClientMetadata: {target_id, current_id} (both are members.id from Legacy DB)
6. Cognito triggers Lambda functions:
   • DefineAuthChallenge: defines CUSTOM_CHALLENGE
   • CreateAuthChallenge: sets challenge parameters with target_id and current_id
   • VerifyAuthChallengeResponse: validates linkages in Legacy DB using target_id and current_id
7. Upon successful linkage validation, Cognito issues tokens for User B
8. Extracts sub (cognito_sub) from User A's AccessToken (from Authorization header, already validated in middleware)
9. Queries mfa_users table using cognito_sub = sub to find User A's mfa_users.id
10. Updates User B's record in mfa_users table:
    • Sets switched_by_id = User A's mfa_users.id
    • Sets session_access_state = 'full_access' (2FA is bypassed for switch-user)
11. Updates mfa_users.client_id if NULL
12. Returns tokens for User B with session_access_state = 'full_access'

Important Notes:

• This endpoint is called by liaison-platform (not directly by members-api)
• liaison-platform is responsible for:
  • Authenticating User A (via Authorization header with Bearer token)
  • Calling members-api first to validate A ↔ B relationship in legacy DB (member_linkages table)
  • Receiving prepared User B information from members-api (current_id, target_id, target_username, target_email, target_external_user_id)
• Auth API middleware validates access token from Authorization header to identify User A (signature, expiration, issuer)
• Lambda functions validate linkages in Legacy DB (member_linkages table) using target_id and current_id (both are members.id)
• If User B does not exist, automatic migration is performed using provided data (Auth API cannot connect to Legacy DB)

Username Format:

• Username format: members_api.{external_user_id}
• Example: members_api.12345

Automatic Migration:

• If User B does not exist in Cognito, Auth API creates the user using:
  • target_username (cognito username)
  • target_email (email address)
  • target_external_user_id (external user identifier)
• User is created with email_verified = true, custom:external_user_id = target_external_user_id, and in FORCE_CHANGE_PASSWORD state
• mfa_users record is created with cognito_sub already set

Session Access State:

• full_access: User has full access immediately (2FA is bypassed for switch-user)
  • Switch-user bypasses 2FA verification when switched_by_id is set
  • User B's session_access_state is always set to 'full_access' after successful switch, regardless of 2FA settings
  • This allows User A (who is already authenticated) to seamlessly switch to User B without additional verification

Login Method:

• switch_user: Account switching between linked accounts

Retrieve current authentication method configuration for the logged-in user. Returns password status, 2FA settings, phone verification status, and passkey count.

Update user's authentication method configuration with password re-authentication.

This endpoint is used when a user who is currently logged in with password authentication wants to change their MFA settings. Before allowing the settings change, the system requires the user to re-authenticate using their password to verify their identity.

Flow Overview:

1. User who is logged in with password authentication wants to update MFA settings
2. User provides current password for identity verification
3. User provides new MFA settings configuration in the request body
4. System verifies the password and, if successful, updates the MFA settings with the provided configuration

Identity Verification:

• User must re-authenticate using password even though they are already logged in
• This ensures that only the authenticated user can modify their security settings
• Password is required in the request body for verification

MFA Settings Options (for users logged in with password):

• User can enable 2FA with method phone (phone call 2FA for password login)
• User can enable 2FA with method passkey (switch to passkey authentication)

MFA Settings Format:

• twofa_enabled: Boolean to enable/disable 2FA
• twofa_method: String enum (phone or passkey) to specify the 2FA method

Note: This endpoint is specifically for users who are currently logged in with password authentication.

Validation rules:

• twofa_enabled and twofa_method are required in mfa_settings
• When twofa_method is phone: 2FA (Caller ID) requires verified phone number
• When twofa_method is passkey: User must have at least one registered passkey device
• Settings are only updated if password verification succeeds

Retrieve detailed information about phone-based 2FA settings (phone number, country code, and verification timestamp) for the authenticated user

Initiate phone number registration for new users

Retrieve status of phone verification process.

Initiate phone call verification for 2FA

Verify password and initiate phone call verification to update MFA settings.

This endpoint is used when a user who is currently logged in with password + 2FA phone call authentication wants to change their MFA settings (e.g., switch to passkey). Before allowing the settings change, the system requires the user to:

1. Re-authenticate using their password to verify their identity
2. Complete phone call verification to confirm the change

Flow Overview:

1. User who is logged in with password + 2FA phone call wants to update MFA settings
2. User provides current password for identity verification
3. System verifies the password
4. If password verification succeeds, system calls Phone System to initiate phone call verification
5. System returns phone call verification information (dedicated phone number, session ID, etc.)
6. User receives phone call and verifies via Phone System
7. User checks verification status via /call/status endpoint
8. After successful verification, user calls /call/update-mfa-settings/finish to complete the MFA settings update

Identity Verification:

• User must re-authenticate using password even though they are already logged in
• This ensures that only the authenticated user can modify their security settings
• Password verification is required before initiating phone call verification

Prerequisites:

• User must be currently logged in with password + 2FA phone call authentication (valid access token required)
• User must have a verified phone number registered

Complete MFA settings update after successful phone call verification.

This endpoint is called after the user has successfully completed phone call verification via /call/status endpoint. The endpoint updates the MFA settings with the provided configuration.

Flow Overview:

1. User has completed phone call verification (verified via /call/status endpoint)
2. User calls this endpoint with the new MFA settings configuration
3. System validates the settings and updates the MFA configuration
4. System returns the updated MFA settings

MFA Settings Options (for users logged in with password + 2FA phone call):

• User can switch to passkey authentication (twofa_enabled: true, twofa_method: "passkey")
• Important: Once 2FA is enabled, it cannot be disabled (security requirement)
• User cannot set twofa_enabled: false or twofa_method: null (returns 400 Bad Request with CANNOT_DISABLE_2FA error)

MFA Settings Format:

• twofa_enabled: Boolean to enable/disable 2FA (must be true for this endpoint - cannot disable 2FA)
• twofa_method: String enum (passkey) to specify the 2FA method. Must be passkey when switching to passkey authentication

Validation rules:

• twofa_enabled and twofa_method are required in mfa_settings
• twofa_enabled must be true (cannot disable 2FA once enabled)
• Settings are only updated if phone call verification was successful

Initiate phone number change process.

Cancel ongoing phone verification process

Verify external ID and initiate recovery process.

Flow:

1. Verifies the username and password is valid.
2. Initiates recovery session.

Initiate phone verification for account recovery (e.g., lost passkey)

Retrieve status of phone verification process during account recovery (login recovery).

Cancel ongoing phone verification process during account recovery (login recovery).

Initialize passkey verification for authenticated users. Always returns a WebAuthn challenge response.

Finish passkey verification and receive auth code

Initialize passkey re-authentication challenge for updating MFA settings.

This endpoint is used when a user who is currently logged in with passkey authentication wants to change their MFA settings. Before allowing the settings change, the system requires the user to re-authenticate using their passkey to verify their identity.

Flow Overview:

1. User calls this endpoint to initiate the passkey re-authentication challenge
2. System returns a WebAuthn challenge that the user must complete
3. User completes passkey authentication via /passkey/update-mfa-settings/finish endpoint
4. If verification succeeds, MFA settings are updated with the provided configuration

Prerequisites:

• User must be currently logged in with passkey authentication (valid access token required)
• User must have at least one registered passkey device

Response:

• Always returns a WebAuthn challenge response that can be used with the browser's WebAuthn API
• The challenge must be completed within the session timeout period

Verify passkey signature and update MFA settings.

This endpoint is used when a user who is currently logged in with passkey authentication wants to change their MFA settings. Before allowing the settings change, the system requires the user to re-authenticate using their passkey to verify their identity.

Flow Overview:

1. User initiates MFA settings update via /passkey/update-mfa-settings/start to get a WebAuthn challenge
2. User completes passkey authentication (WebAuthn challenge response)
3. This endpoint verifies the passkey signature and, if successful, updates the MFA settings with the provided mfa_settings configuration

Identity Verification:

• User must re-authenticate using passkey even though they are already logged in
• This ensures that only the authenticated user can modify their security settings

MFA Settings Update:

• The mfa_settings object contains the new configuration that will be applied after successful passkey verification
• Settings are only updated if passkey verification succeeds

MFA Settings Options (for users logged in with passkey):

• User can switch to only password authentication (twofa_enabled: false, twofa_method: null)
• User can enable password authentication with phone call 2FA (twofa_enabled: true, twofa_method: "phone")

MFA Settings Format:

• twofa_enabled: Boolean to enable/disable 2FA
• twofa_method: String enum (phone or null) to specify the 2FA method. Set to null when disabling 2FA (switching to only password)

Retrieve list of all registered passkey devices for the authenticated user. Returns device name, creation date, and last used timestamp for each passkey.

Update the display name of a registered passkey device. User can only rename their own passkeys.

Validation rules:

• Device name cannot be empty
• Maximum length: 255 characters
• Must be the passkey owner