> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Start Forgot Password Workflow

API documentation for the FusionAuth Start Forgot Password Workflow API.

# 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](https://fusionauth.io/docs/apis/users/change-password.md) 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](https://fusionauth.io/docs/apis/users/change-password.md) API.

note

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

[!No Authentication Required](https://fusionauth.io/docs/apis/authentication.md#no-authentication-required)

Start the forgot password workflow without an API Key.

POST/api/user/forgot-password

OpenAPI Spec

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Body

`applicationId`UUIDoptionalAvailable 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.

`loginId`Stringrequired

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

`loginIdTypes`Array<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`

note

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.

`state`Objectoptional

An optional object that will be returned un-modified when you complete the forgot password request using the [Change a User's Password API](https://fusionauth.io/docs/apis/users/change-password.md). This may be useful to return the user to particular state once they complete the password change.

*Example Request JSON*

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

### Using an API key

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Start the forgot password workflow using an API key

POST/api/user/forgot-password

OpenAPI Spec

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Body

`applicationId`UUIDoptionalAvailable 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.

`changePasswordId`Stringoptional

The optional change password Id to be used on the [Change a User's Password](https://fusionauth.io/docs/apis/users/change-password.md) 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.

`loginId`Stringrequired

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

`loginIdTypes`Array<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`

note

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.

`sendForgotPasswordEmail`BooleanoptionalDefaults 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.

Available since 1.43.0

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.

`sendForgotPasswordMessage`BooleanoptionalDefaults 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.

`state`Objectoptional

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*

```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](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). |
| 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

`changePasswordId`String

The change password Id that was generated by this API request. This identifier may be used by the [Change a User's Password](https://fusionauth.io/docs/apis/users/change-password.md) 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*

```json
{
  "changePasswordId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}
```