Resetting Passwords

DANGER

This document has not been updated since version 0.0.3 and is not ready for production. It will be updated before version 1.0 of the project is released.

Enable users to reset their passwords during the log in process.

How it works

Submit an email address to the API for lookup. Upon success, an email is sent to the user containing a tokened link back to your reset password page for submission with the new password.

Prerequisites

Your application must have a reset URL defined in the dashboard settings. This URL serves as the base endpoint for the link included in the email sent to the user.

Lookup email address

Provide an email address to receive a system-generated email containing instructions for resetting a password.

Request

POST /v1/auth/forgot-password
{
  "email": "jdoe@acmecorp.com"
}

Parameter	Type	Description
email	Required string	The email address to lookup.

Response

Upon success, an email is sent to the user with instructions containing a tokened link to your reset password page.

The response contains FYI data.

{
  "user_ids: [
    "usr_1234567890",
    ...
  ]
}

Property	Type	Description
user_ids	Array	For your information, an array containing the user IDs associated with the email address. (An email address may represent multiple users.)

Upon error, the API will respond with an error object.

// error object
{
  "error": {
   ...
  }
}

Preflight token validation

Optionally, you can to verify the email token before presenting the user with the reset password form.

Request

GET /v1/auth/reset-password/:token

Parameter	Type	Description
token	Required string	The token included in the reset password email sent to the user.

Response

Upon success, the API will respond with the token submitted.

{
  "token": "XiMs2UXizVaJnw8rMKJW"
}

Upon error, the API will respond with an error object.

// error object
{
  "error": {
   ...
  }
}

Reset password

The link in the reset password email includes a token that needs to be submitted with the new password.

var token = new URLSearchParams(window.location.hash).get('token');

Request

POST /v1/auth/reset-password
{
  "token": token,
  "password": password,
  "confirm": confirm
}

Parameter	Type	Description
token	Required string	The token included in the reset password instructional email sent to the user.
password	Required string	The new password. The new password must be at least 8 characters and cannot be the username.
confirm	Required string	Confirm the new password.

Response

Upon success, the API will respond with the User object, and you can begin the user log in process.

// user object
{
  "id": "usr_1234567890"
  ...
}

Upon error, the API will respond with an error object.

// error object
{
  "error": {
   ...
  }
}