How do I use the forgot password flow in Amazon Cognito?

2 minute read

I need to use the forgot password flow to help users change their passwords in Amazon Cognito.


An Amazon Cognito user can invoke the ForgotPassword API to initiate a forgot password flow to reset their user password.

Follow these steps to set up the forgot password flow to change a user's password in Amazon Cognito:

1.    Invoke the ForgotPassword API to send a message to the user that includes a confirmation code that's required to reset the user's password.

Important: In the example AWS Command Line Interface (AWS CLI) commands, replace all instances of example strings with your values. (For example, replace "example_client_id" with your client ID.)

Example forgot-password command:

aws cognito-idp forgot-password --client-id example_client_id --username example_user_name


  "CodeDeliveryDetails": {
    "Destination": "t***@g***",
    "DeliveryMedium": "EMAIL",
    "AttributeName": "email"

The confirmation code message is sent to the user's verified email address or verified phone number. The recovery method can be customized in the AccountRecoverySetting parameter. The confirmation code message in the example goes to the user's verified email address. Your configuration depends on your use case.

Note: If neither a verified phone number nor a verified email address exists for a user, then an InvalidParameterException error is thrown. To learn more about configuring email address and phone number verification, see Configuring email or phone verification.

2.    Invoke the ConfirmForgotPassword API so that the user can enter the confirmation code to reset their password.

Example confirm-forgot-password command:

aws cognito-idp confirm-forgot-password --client-id example_client_id --password example_password --confirmation-code example_confirmation_code

3.    If necessary, customize the password recovery error responses by setting PreventUserExistenceErrors to Enabled. To learn more, see Managing error responses.

4.    If your app client is configured with a client secret in the user pool, then you must provide the secret hash. To learn more, see How do I troubleshoot "Unable to verify secret hash for client <client-id>" errors from my Amazon Cognito user pools API?

AWS OFFICIALUpdated a year ago