Skip to content

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.

Images

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

sh
POST /v1/auth/forgot-password
{
  "email": "jdoe@acmecorp.com"
}
ParameterTypeDescription
emailRequired stringThe 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.

js
{
  "user_ids: [
    "usr_1234567890",
    ...
  ]
}
PropertyTypeDescription
user_idsArrayFor 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.

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

Preflight token validation

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

Request

sh
GET /v1/auth/reset-password/:token
ParameterTypeDescription
tokenRequired stringThe token included in the reset password email sent to the user.

Response

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

js
{
  "token": "XiMs2UXizVaJnw8rMKJW"
}

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

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

Reset password

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

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

Request

sh
POST /v1/auth/reset-password
{
  "token": token,
  "password": password,
  "confirm": confirm
}
ParameterTypeDescription
tokenRequired stringThe token included in the reset password instructional email sent to the user.
passwordRequired stringThe new password. The new password must be at least 8 characters and cannot be the username.
confirmRequired stringConfirm the new password.

Response

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

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

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

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