Search code examples
restrestful-architecturerestful-url

RESTFul API Design Suggestion for forgot password flow

I'm working on designing Restful API for forgot password flow. The flow to be used in web application is below:

1) User enters user id
2) Application validates user id and sends verification token to user's email address
3) User will be asked for validation code and new password
4) User will enter validation code and new password
5) Application validates token and updates password.

I would appreciate your suggestions on how this flow can be translated to Restful API's.

Thank you,
Raj

Solution

  • This is a very standard design, I think you can find lots of resources, or even reset your own password on some website and see how that works.

    The basics:

    • The client will make a POST request when sending the user id. Note that it's a good idea to NOT say if the user id / email is valid (to avoid brute force checking of user id / email existing). Also, make it so that you can't request another password reset until the previous token has expired (to prevent DoS attacks).
    • As you said, the server will check the associated email and eventually send the token.
    • There is no actual need for the user to enter the validation token. Just like most sites do, you can embed that in the link that you send in the email. Remember to set a reasonable expire time for the token (maybe one hour?). Here you should already check the token validity.
    • The link with the token will be a GET request to a specific page where the user is automatically authenticated and can enter the new password (again: remember the expiry time on the token).
    • The user will enter the new password with a POST request, you check the token validity again, and if everything matches, you update the password.

    In terms of POST and GET calls that can be something like:

    • POST https://www.yoursite.com/resetpassword, with the user id / email in the body. Don't put the user id / email as a query or path parameter, especially if you have ads / banners on the page, because they might be able to get that data.

    • GET https://www.yoursite.com/password?token=dhs3541hpk43hokdsau9ef where the token is associated with the user id / email resetting the password (you should have this in a database). Here the token is validated for the first time and the user can enter the new password in a form. Note that this can be the same form that you use when the user is changing the password, just without the Old password field. Note that you should NOT have banners / ads on this page, ever. That would be a serious security risk.

    • POST https://www.yoursite.com/password?token=dhs3541hpk43hokdsau9ef with the new password in the body. Again, don't put banners / ads on this page. The server will check the token again and if it matches, update the password. Then the server will mark the token as invalid / expired.