Start Forgot Password Workflow

This API is used to start the forgot password workflow for a single User.

For example, on your login form you may have a button for Forgot your password. This would be the API you would call to initiate the request for the user. If the email configuration is complete, the user will be sent the forgot password email containing a link containing the changePasswordId. The provided link should take the user to a form that allows them to change their password. This form should contain a hidden field for the changePasswordId generated by this API.

By default the changePasswordId is valid to be used with the Change Password API for 10 minutes. If a 404 is returned when using this Id to change the password, the workflow will need to be started again to generate a new identifier. This duration can be modified using the Tenant API or in the FusionAuth UI.

You may optionally authenticate this request with an API key to allow for some additional request parameters and the generated changePasswordId will be returned in the JSON body. This may be helpful if you wish to use your own email system or you have an alternative method to call the Change Password API.

If FusionAuth sends an email to the user, it will either use the email top level property on the user or it will use a custom data attribute named email as well (i.e. data.email). This allows you to have a user that has no email address for login or allow distinct users to share email addresses.

Request#

Calling this API without an API key always attempts to send a message to the user. If FusionAuth is unable to deliver a message based on the resolved identity and tenant configuration, a forgot password workflow will not be started.

Without an API key#

Start the forgot password workflow without an API Key.

POST/api/user/forgot-password

OpenAPI Spec

Request Headers#

X-FusionAuth-TenantIdStringoptional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request because the input parameters by themselves do not indicate which tenant the request is intended.

The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body#

applicationIdUUIDoptionalAvailable since 1.21.0

The Id of the application. If valid, the email or message template configured in the Application settings will be used, if present. If not present, the template configured in the Tenant settings will be used. In either case, the corresponding Application object will be available to the template.

loginIdStringrequired

The login identifier of the user. The login identifier can be one of the following (see loginIdTypes for information on which of these identifiers will be used):

Email address
Phone number (if phoneNumber is included in loginIdTypes)
Username

loginIdTypesArray<String>optionalDefaults to [email, username]Available since 1.59.0

The identity types that FusionAuth will compare the loginId to. Can be one or more of the following:

email
phoneNumber
username

The order is significant. If ["email", "username"] is supplied with a loginId value of terry@example.com, then a user with terry@example.com as their email address will match first before any user with terry@example.com as their username.

stateObjectoptional

An optional object that will be returned un-modified when you complete the forgot password request using the Change a User's Password API. This may be useful to return the user to particular state once they complete the password change.

Example Request JSON

{
  "applicationId": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
  "loginId": "example@fusionauth.io"
}

Using an API key#

Start the forgot password workflow using an API key

POST/api/user/forgot-password

OpenAPI Spec

Request Headers#

X-FusionAuth-TenantIdStringoptional

The unique Id of the tenant used to scope this API request.

The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body#

applicationIdUUIDoptionalAvailable since 1.21.0

changePasswordIdStringoptional

The optional change password Id to be used on the Change a User's Password API.

It is recommended to omit this parameter and allow FusionAuth to generate the identifier. Use this parameter only if you must supply your own value for integration into existing systems.

loginIdStringrequired

The login identifier of the user. The login identifier can be one of the following (see loginIdTypes for information on which of these identifiers will be used):

Email address
Phone number (if phoneNumber is included in loginIdTypes)
Username

loginIdTypesArray<String>optionalDefaults to [email, username]Available since 1.59.0

The identity types that FusionAuth will compare the loginId to. Can be one or more of the following:

email
phoneNumber
username

sendForgotPasswordEmailBooleanoptionalDefaults to trueDEPRECATED

Whether or not calling this API should attempt to send the user an email using the configured Forgot Password email template. Setting this to false will begin the Forgot Password workflow without sending an email and only create the changePasswordId, this may be useful if you want to send an email outside of FusionAuth, or complete this workflow without the use of email.

When setting this to false you will not be required to have configured the Forgot Password email template in the FusionAuth tenant. Prior to 1.43.0, even when setting this to false, the Tenant would be required to have configured the Forgot Password email template.

Deprecated since 1.59.0

Prefer using the new sendForgotPasswordMessage field.

sendForgotPasswordMessageBooleanoptionalDefaults to trueAvailable since 1.59.0

Determines whether a forgot password message is sent to the user. Setting this to true will cause a message to be sent. Setting this to false will begin the Forgot Password workflow without sending a message and only create the changePasswordId, which may be useful if you want to send a message outside of FusionAuth, or complete this workflow without the use of email/SMS.

The template and delivery method are based on the type of the identity resolved by the request.

FusionAuth will attempt to deliver the message via SMS when the provided login Id and type resolve to a phone number identity. This requires tenant.phoneConfiguration.forgotPasswordTemplateId to be configured, otherwise the request will fail.
If the provided login Id and type resolve to an email or username identity, FusionAuth will attempt to deliver the message via email. This requires tenant.emailConfiguration.forgotPasswordEmailTemplateId to be configured, otherwise the request will fail.

stateObjectoptional

An optional object that will be returned un-modified when you complete the forgot password request. This may be useful to return the user to particular state once they complete the password change.

Example Request JSON

{
  "applicationId": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
  "changePasswordId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4",
  "loginId": "example@fusionauth.io",
  "sendForgotPasswordMessage": false,
  "state": {
    "lastPage": "/foo/baz"
  }
}

Response#

Response Codes

Code	Description
200	The request was successful. A JSON response body will be provided when authenticated using an API key, when the API key has been omitted from the request, no response body is provided.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
403	The forgot password functionality has been disabled. This is caused by an administrator setting the Forgot Password Email Template to the option Feature Disabled. No template selected. in the Tenant Email configuration. See Tenants -> Email -> Template settings in the FusionAuth admin UI.
404	The User could not be found.
422	The User does not have an email address, this request cannot be completed. Before attempting the request again add an email address to the user.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

changePasswordIdString

The change password Id that was generated by this API request. This identifier may be used by the Change a User's Password API. This field is only returned in the JSON response body if the request was authenticated using an API key, if an API key is not used no response body is returned.

Example Response JSON

{
  "changePasswordId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}