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

# Validate a password change

API documentation for the FusionAuth Validate a password change API.

# Validate a password change

## Request

This API is used to validate whether a request to [change a user's password](https://fusionauth.io/docs/apis/users/change-password.md) will require MFA (via a `trustToken`). There are 3 ways to call the endpoint:

1.  Validate a `changePasswordId` without authentication
2.  Validate user password change using a JWT
3.  Validate user password change using a `loginId` with API key

The first case will also verify that a `changePasswordId` is valid. This usage is generally intended to be part of an email or SMS workflow and does not require authentication. The `changePasswordId` used on this API request will have been previously generated by the [Start Forgot Password API](https://fusionauth.io/docs/apis/users/forgot-password.md) or by using the Forgot Password workflow on the FusionAuth login page. Use this API to validate the `changePasswordId` before requesting a password change.

### Using a change password ID

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

Validate a changePasswordId

GET/api/user/change-password/{changePasswordId}

OpenAPI Spec

#### Request Parameters

`changePasswordId`Stringrequired

The `changePasswordId` that is used to identify the user after the [Start Forgot Password workflow](https://fusionauth.io/docs/apis/users/forgot-password.md) has been initiated.

`ipAddress`StringoptionalAvailable since 1.62.0

The IP address of the end-user that is changing their password. If this value is omitted FusionAuth will attempt to obtain the IP address of the client, the value will be that of the `X-Forwarded-For` header if provided or the last proxy that sent the request. This value may be used by an MFA requirement lambda to determine if multi-factor authentication should be required.

note

Since version 1.62.0, the metadata fields below may be used by an MFA requirement lambda to determine if multi-factor authentication should be required.

`metaData.device.description`StringoptionalAvailable since 1.62.0

A human readable description of the device used. This meta data is used to describe the refresh token that may be generated for this request.

`metaData.device.lastAccessedAddress`StringoptionalAvailable since 1.62.0

The IP address which made this request.

`metaData.device.name`StringoptionalAvailable since 1.62.0

A human readable name of the device used. This meta data is used to describe the refresh token that may be generated for this request.

`metaData.device.type`StringoptionalAvailable since 1.62.0

The type of device represented by the `device` parameter.

Prior to version 1.46.0, this value was restricted to the following types:

*   `BROWSER`
*   `DESKTOP`
*   `LAPTOP`
*   `MOBILE`
*   `OTHER`
*   `SERVER`
*   `TABLET`
*   `TV`
*   `UNKNOWN`

In version `1.46.0` and beyond, this value can be any string value you'd like, have fun with it!

This meta data is used to describe the refresh token that may be generated for this request.

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

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

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. 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.

The "Validate user password change using a JWT or `loginId`" cases are used to verify whether MFA is required to change a user's password based solely on the user's JWT or `loginId`. It does not validate a specific `changePasswordId` and is instead meant to validate whether MFA is required before [changing the user's password](https://fusionauth.io/docs/apis/users/change-password.md) using a JWT or `loginId`.

### Using a JWT

[!JWT Authentication](https://fusionauth.io/docs/apis/authentication.md#jwt-authentication)

Validate user password change using a JWT

GET/api/user/change-password

OpenAPI Spec

#### Request Parameters

`ipAddress`StringoptionalAvailable since 1.62.0

The IP address of the end-user that is changing their password. If this value is omitted FusionAuth will attempt to obtain the IP address of the client, the value will be that of the `X-Forwarded-For` header if provided or the last proxy that sent the request. This value may be used by an MFA requirement lambda to determine if multi-factor authentication should be required.

note

Since version 1.62.0, the metadata fields below may be used by an MFA requirement lambda to determine if multi-factor authentication should be required.

`metaData.device.description`StringoptionalAvailable since 1.62.0

A human readable description of the device used. This meta data is used to describe the refresh token that may be generated for this request.

`metaData.device.lastAccessedAddress`StringoptionalAvailable since 1.62.0

The IP address which made this request.

`metaData.device.name`StringoptionalAvailable since 1.62.0

A human readable name of the device used. This meta data is used to describe the refresh token that may be generated for this request.

`metaData.device.type`StringoptionalAvailable since 1.62.0

The type of device represented by the `device` parameter.

Prior to version 1.46.0, this value was restricted to the following types:

*   `BROWSER`
*   `DESKTOP`
*   `LAPTOP`
*   `MOBILE`
*   `OTHER`
*   `SERVER`
*   `TABLET`
*   `TV`
*   `UNKNOWN`

In version `1.46.0` and beyond, this value can be any string value you'd like, have fun with it!

This meta data is used to describe the refresh token that may be generated for this request.

### Using a login ID

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

Validate user password change using a loginId

GET/api/user/change-password?loginId={loginId}

OpenAPI Spec

#### Request Parameters

`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.61.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.

`ipAddress`StringoptionalAvailable since 1.62.0

The IP address of the end-user that is changing their password. If this value is omitted FusionAuth will attempt to obtain the IP address of the client, the value will be that of the `X-Forwarded-For` header if provided or the last proxy that sent the request. This value may be used by an MFA requirement lambda to determine if multi-factor authentication should be required.

note

Since version 1.62.0, the metadata fields below may be used by an MFA requirement lambda to determine if multi-factor authentication should be required.

`metaData.device.description`StringoptionalAvailable since 1.62.0

A human readable description of the device used. This meta data is used to describe the refresh token that may be generated for this request.

`metaData.device.lastAccessedAddress`StringoptionalAvailable since 1.62.0

The IP address which made this request.

`metaData.device.name`StringoptionalAvailable since 1.62.0

A human readable name of the device used. This meta data is used to describe the refresh token that may be generated for this request.

`metaData.device.type`StringoptionalAvailable since 1.62.0

The type of device represented by the `device` parameter.

Prior to version 1.46.0, this value was restricted to the following types:

*   `BROWSER`
*   `DESKTOP`
*   `LAPTOP`
*   `MOBILE`
*   `OTHER`
*   `SERVER`
*   `TABLET`
*   `TV`
*   `UNKNOWN`

In version `1.46.0` and beyond, this value can be any string value you'd like, have fun with it!

This meta data is used to describe the refresh token that may be generated for this request.

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

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

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. 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.

## Response

This JSON response body will only be returned when a validation error occurs.

A successful response will not contain a response body.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful and can be used as part of a request to [change the user's password](#change-a-users-password). |
| 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.  
Beginning in version `1.33.0` a status code of `400` may also be used to indicate additional MFA trust is required  
to [change the user's password](#change-a-users-password). In this case the following error will be returned.  
*Example Response JSON*

```json
{
  "generalErrors": [
    {
      "code": "[TrustTokenRequired]",
      "message": "This request requires a Trust Token. Use the Start Two-Factor API to obtain a Trust Token required to complete this request."
    }
  ]
}
```

To complete a request to [change the user's password](https://fusionauth.io/docs/apis/users/change-password.md), you must obtain a `trustToken` using a [Multi-Factor Login request](https://fusionauth.io/docs/apis/login/complete-mfa.md). |
| 404 | The `changePasswordId` is incorrect or expired or the user could not be found. |