/Docs

Validate a password change

Request#

This API is used to validate whether a request to change a user's password 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 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
Validate a changePasswordId
GET/api/user/change-password/{changePasswordId}
OpenAPI Spec

Request Parameters#

changePasswordIdStringrequired

The changePasswordId that is used to identify the user after the Start Forgot Password workflow has been initiated.

ipAddressStringoptionalAvailable 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.

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.descriptionStringoptionalAvailable 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.lastAccessedAddressStringoptionalAvailable since 1.62.0

The IP address which made this request.

metaData.device.nameStringoptionalAvailable 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.typeStringoptionalAvailable 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-TenantIdStringoptional

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 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 using a JWT or loginId.

Using a JWT#

JWT Authentication
Validate user password change using a JWT
GET/api/user/change-password
OpenAPI Spec

Request Parameters#

ipAddressStringoptionalAvailable 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.

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.descriptionStringoptionalAvailable 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.lastAccessedAddressStringoptionalAvailable since 1.62.0

The IP address which made this request.

metaData.device.nameStringoptionalAvailable 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.typeStringoptionalAvailable 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
Validate user password change using a loginId
GET/api/user/change-password?loginId={loginId}
OpenAPI Spec

Request Parameters#

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

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.descriptionStringoptionalAvailable 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.lastAccessedAddressStringoptionalAvailable since 1.62.0

The IP address which made this request.

metaData.device.nameStringoptionalAvailable 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.typeStringoptionalAvailable 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-TenantIdStringoptional

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 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
CodeDescription
200The request was successful and can be used as part of a request to change the user's password.
400The request was invalid and/or malformed. The response will contain an Errors 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. In this case the following error will be returned.

Example Response 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, you must obtain a trustToken using a Multi-Factor Login request.
404The changePasswordId is incorrect or expired or the user could not be found.