Skip to main content

Forgot/Reset Password

This page describes the user flow when a user tries to reset the password

Reset Password via OTP

The user should be asked to enter their email address to send an OTP to the same.

  • api/auth/v1/users/send-otp. This is a POST request method. The API returns a 200 on successfully sending the OTP. Refer to Swagger API docs for more info on API usage.

  • api/auth/v1/users/reset-password. This is a POST method, its payload consists of OTP received in the earlier response, same email address and a new password.

  • If the OTP sent in the above POST request is invalid, the API returns HTTP 401 with "OTP does not match", as the message is based on time-based OTP standards.

  • The API returns 200, if the password is reset successfully.


    Sample CURL

    curl --location --request POST 'https://<publisher-website-url>/api/auth/v1/users/reset-password'
    --data-raw '{"otp":"40580","email":"","new-password":"new*123password#"}'

    API Sequence Diagram


Forgot Password via token

A reset password link will be sent to the user's email.

  • api/auth/v1/users/forgot-password. This is a POST request method and its payload consists of email address of the user wishing to set a new password.

  • A token record is created against each user id in the database. If the request fails, HTTP 500 is returned as response which could be because of improper configuration of the email provider. Please contact support to know more about this.

  • If there is an error, the API returns 422 with Invalid current-host url. as its response message.

  • api/auth/v1/users/reset-password-with-token. This is a POST request method whose request body consists of new-password, confirm-password and token.

  • When the new password and confirm password do not match, the API returns 400 with a response message as new-password and confirm-password should be same.

  • When the new password is empty, the API returns 400 with as response message as new-password should not be empty.

  • If the link has expired, the API returns 401 with This link to reset your password has expired.","code":"#token-consumed as its response.

  • If there is an error finding the token or the token has expired the API returns 401 with Token could not be found, or is expired,code: "#invalid-token as its response.

  • If the password has been reset successfully then the API returns 200 with Password reset successful. Email has been set as the username. as its response.


    Sample CURL

    curl --location --request POST 'https://<publisher-website-url>/api/auth/v1/users/forgot-password'
    --data-raw '{"email":""}'
    curl --location --request POST 'https://<publisher-website-url>/api/auth/v1/users/reset-password-with-token'
    --data-raw '{"new-password":"password","confirm-password":"password","token":"36afebb2-b2c1-47f3-a80e-0510ad2fdce1"}'

    API Sequence Diagram