Unauthenticated users
We do a PUT request on a api/v1/account/password endpoint and require a parameter with the corresponding account email to identify the account for which the user wants to reset (update) the password:
PUT : /api/v1/account/password?email={email@example.com}
Note: As @DougDomeny mentioned in his comment passing the email as a query string in the url is a security risk. GET parameters are not exposed when using https (and you should always use a proper https connection for such requests) but there are other security risks involved. You can read more on this topic in this blog post here.
Passing the email in the request body would be a more secure alternative to passing it as a GET param:
PUT : /api/v1/account/password
Request body:
{
"email": "email@example.com"
}
The response has a 202 accepted response meaning:
The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
The user will receive an email at email@example.com and processing the update request depends on actions taken with the link from the email.
https://example.com/password-reset?token=1234567890
Opening the link from this email will direct to a reset password form on the front end application that uses the reset password token from the link as input for a hidden input field (the token is part of the link as a query string). Another input field allows the user to set a new password. A second input to confirm the new password will be used for validation on front-end (to prevent typos).
Note: In the email we could also mention that in case the user didn't initialize any password reset he/she can ignore the email and keep using the application normally with his/her current password
When the form is submitted with the new password and the token as inputs the reset password process will take place. The form data will be sent with a PUT request again but this time including the token and we will replace the resource password with a new value:
PUT : /api/v1/account/password
Request body :
{
"token":"1234567890",
"new":"password"
}
The response will be a 204 no content response
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation. The response MAY include new or updated metainformation in the form of entity-headers, which if present SHOULD be associated with the requested variant.
Authenticated users
For authenticated users that want to change their password the PUT request can be performed immediately without the email (the account for which we are updating the password is known to the server). In such case the form will submit two fields:
PUT : /api/v1/account/password
Request body:
{
"old":"password",
"new":"password"
}
