/Docs

Change a User's Password

This API is used to change the User's password.

This API may be used as the second part of the Start Forgot Password workflow. For example, after the User is sent an email or SMS message that contains a link to a web form that allows them to update their password you will call this API with the changePasswordId and their updated password. If the changePasswordId is valid then the User's password will be updated.

This API may also be used separately from the Start Forgot Password workflow by omitting the changePasswordId and using the loginId instead.

By default the changePasswordId is valid for 10 minutes after it was generated. If a 404 is returned when using the change password Id, 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 admin UI.

When this API successfully completes, all refresh tokens and outstanding Change Password Ids (i.e. changePasswordId) currently assigned to the user will be expired or revoked. This means that if a user is using a refresh token they will be forced to re-authenticate with their new password.

Request#

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 workflow or by using the Forgot Password workflow on the FusionAuth login page.

Using a change password ID#

No Authentication Required
Change a User's password using the change password Id
POST/api/user/change-password
OpenAPI Spec
No Authentication Required
Change a User's password using the change password Id
POST/api/user/change-password/{changePasswordId}
OpenAPI Spec

Request Parameters#

changePasswordIdStringrequiredDEPRECATED

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

If this changePasswordId was sent via an email to the User by FusionAuth during User create in order to set up a new password, or as part of a Forgot Password request, then successful use of this identifier to change the User's password will implicitly complete Email Verification if not already verified and the Tenant configuration has enabled implicit email verification.

Deprecated since 1.33.0

This value can still be provided on the URL segment as shown in the above example, but it is recommended you send this value in the request body instead using the changePasswordId field. If the value is provided in the URL segment and in the request body, the value provided in the request body will be preferred.

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.

Request Body#

changePasswordIdStringrequiredAvailable since 1.33.0

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

If this changePasswordId was sent via an email to the User by FusionAuth during User create in order to set up a new password, or as part of a Forgot Password request, then successful use of this identifier to change the User's password will implicitly complete Email Verification if not already verified and the Tenant configuration has enabled implicit email verification.

If the changePasswordId is provided in the URL segment and in the request body, the value provided in the request body will be preferred.

currentPasswordStringoptional

The User's current password. When this parameter is provided the current password will be verified to be correct.

passwordStringrequired

The User's new password.

trustChallengeStringoptionalAvailable since 1.33.0

This field is marked optional because it is only required when the user has enabled two-factor authentication, and a trustChallenge was provided on the Two-Factor Start API request. When a user has enabled two-factor authentication this field becomes required if a trustChallenge was provided on the Two-Factor Start API request. When required, this value must be equal to the value provided to the Two-Factor Start API.

trustTokenStringoptionalAvailable since 1.33.0

This field is marked optional, because it is only required when the user has enabled two-factor authentication. When a user has enabled two-factor authentication this field becomes required when attempting to change a password using the changePasswordId.

Example JSON Request

{
  "currentPassword": "too many secrets",
  "password": "Setec Astronomy"
}

This usage requires an API key and allows you to change any user's password if you have a unique login Id.

Using a login ID#

API Key Authentication
Changes a User's password using a login Id.
POST/api/user/change-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.30.0

An optional Application Id. When this value is provided, it will be used to resolve an application specific email or message template if you have configured transactional notifications such as setup password, email verification and others.

If not provided, only the tenant configuration will be used when resolving templates.

currentPasswordStringoptional

The User's current password. When this parameter is provided the current password will be verified to be correct.

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
When this value is provided it should be in place of the `changePasswordId` request parameter. If both the `changePasswordId` and `loginId` are provided on the request, the `changePasswordId` will take precedence.
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.
passwordStringrequired

The User's new password.

trustChallengeStringoptionalAvailable since 1.33.0

This field is marked optional because it is only required when the user has enabled two-factor authentication, and a trustChallenge was provided on the Two-Factor Start API request. When a user has enabled two-factor authentication this field becomes required if a trustChallenge was provided on the Two-Factor Start API request. When required, this value must be equal to the value provided to the Two-Factor Start API.

trustTokenStringoptionalAvailable since 1.33.0

This field is marked optional, because it is only required when the user has enabled two-factor authentication. When a user has enabled two-factor authentication this field becomes required when attempting to change a password using the changePasswordId.

Example JSON Request

{
  "applicationId": "18cec3c9-003b-433f-8412-6e31afca5bcf",
  "currentPassword": "too many secrets",
  "loginId": "cosmo@playtronics.com",
  "password": "Setec Astronomy"
}

Available Since Version 1.5.0

This API will use a JWT as authentication. See JWT Authentication for examples of how you can send the JWT to FusionAuth.

A common use case for using this API with a JWT will be if you want to allow the user to change their own password. Specifically if you are attempting to perform this request in a frontend browser that cannot store an API key.

Because changing a User's password will revoke all existing refresh tokens if you allow the user to change their password they will need to re-authenticate to stay logged into your application if you are utilizing JWTs and Refresh Tokens.

For this reason, this API will return a oneTimePassword that is intended to be used programatically after a Change Password request completes to keep the user logged in and provide a better user experience. A successful login will return you a new access token (JWT) and a refresh token. This will allow you to make the change password workflow seamless to the user.

Using a JWT#

JWT Authentication
Change a User's password using a JWT
POST/api/user/change-password
OpenAPI Spec

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.

Request Body#

currentPasswordStringrequired

The User's current password. This is required when using a JWT to change your password.

passwordStringrequired

The User's new password.

refreshTokenStringoptional

The user's existing refresh token. If you have access to your current refresh token, it can be provided in the request body using this parameter. If the refresh_token cookie also exists and is present on the request it will take precedence over this parameter.

This parameter is used to determine if the oneTimePassword that is returned from this API will be eligible to request a refresh token when used by the Login API. If this parameter is not provided and no cookie is found on the request, a refresh token will not be provided on the Login response when using the returned oneTimePassword.

trustChallengeStringoptionalAvailable since 1.33.0

This field is marked optional because it is only required when the user has enabled two-factor authentication, and a trustChallenge was provided on the Two-Factor Start API request. When a user has enabled two-factor authentication this field becomes required if a trustChallenge was provided on the Two-Factor Start API request. When required, this value must be equal to the value provided to the Two-Factor Start API.

trustTokenStringoptionalAvailable since 1.33.0

This field is marked optional, because it is only required when the user has enabled two-factor authentication. When a user has enabled two-factor authentication this field becomes required when attempting to change a password using the changePasswordId.

Example JSON Request

{
  "currentPassword": "too many secrets",
  "password": "Setec Astronomy"
}

Response#

Response Codes
CodeDescription
200The request was successful. Starting in version 1.5.0 a JSON response body will be returned unless the API was called with an API key was used with a loginId. Prior to version 1.5.0 a JSON body was not returned.
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 trust is required to complete this request. 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 this request you must obtain a trustToken. To obtain a trustToken, complete a Two-Factor Login request.
Beginning in version 1.43.0 a status code of 400 may also indicate that the suppliedcurrentPassword or loginId were incorrect if the call was made with an API key. For security reasons without an API key this will return a 404.
401You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. SeeAuthentication.
404The User could not be found using the changePasswordId or loginId value from the request. If using thechangePasswordId the id is either incorrect or expired. Another reason for this status code is that you have provided thecurrentPassword parameter and it does not match the current password.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

This JSON response body will only be returned when using a changePasswordId parameter or a JWT to change the password.

When calling this API with an API key no response body will be returned.

oneTimePasswordStringAvailable since 1.5.0

A one time password that can be used as a substitute for your loginId and password on the Login API.

stateObjectAvailable since 1.5.0

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

Example Response JSON

{
  "oneTimePassword": "YQNfvoDJy4_0As9iLTk9hpjF5z_C3VWVyBy95vFZr0M"
}