Skip to main content

​
Overview

Password reset is a two-step process:
  1. Request a password reset link via email
  2. Reset the password using the token from the email

​
Step 1: Request Password Reset Link

​
Endpoint

​
method
string
default:"POST"
HTTP Method
​
endpoint
string
default:"/forgot-password"
API Endpoint

​
Authentication

This endpoint does not require authentication (uses guest middleware).

​
Request Body

​
email
string
required
The email address of the account to reset.
  • Must be a valid email format
  • Must exist in the database

​
Response

​
status
string
Status message indicating the reset link was sent.

​
Example Request

cURL
curl -X POST https://your-api.com/forgot-password \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]"
  }'
Next.js
const response = await fetch('http://localhost:8000/forgot-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
  }),
});

const data = await response.json();
console.log(data.status); // "We have emailed your password reset link!"

​
Success Response

{
  "status": "We have emailed your password reset link!"
}

​
Error Responses

​
Email Not Found (422)

{
  "message": "We can't find a user with that email address.",
  "errors": {
    "email": [
      "We can't find a user with that email address."
    ]
  }
}

​
Validation Error (422)

{
  "message": "The email field is required.",
  "errors": {
    "email": [
      "The email field is required."
    ]
  }
}

​
Step 2: Reset Password

​
Endpoint

​
method
string
default:"POST"
HTTP Method
​
endpoint
string
default:"/reset-password"
API Endpoint

​
Authentication

This endpoint does not require authentication (uses guest middleware).

​
Request Body

​
token
string
required
The password reset token received via email.
​
email
string
required
The email address of the account.
  • Must be a valid email format
​
password
string
required
The new password.
  • Must meet Laravel’s default password requirements
  • Must be confirmed with password_confirmation
​
password_confirmation
string
required
Password confirmation. Must match the password field.

​
Response

​
status
string
Status message indicating the password was reset successfully.

​
Example Request

cURL
curl -X POST https://your-api.com/reset-password \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "token": "a1b2c3d4e5f6...",
    "email": "[email protected]",
    "password": "NewSecurePassword123!",
    "password_confirmation": "NewSecurePassword123!"
  }'
Next.js
// Extract token from URL (e.g., /reset-password?token=...)
const token = searchParams.get('token');

const response = await fetch('http://localhost:8000/reset-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    token,
    email: '[email protected]',
    password: 'NewSecurePassword123!',
    password_confirmation: 'NewSecurePassword123!',
  }),
});

const data = await response.json();
console.log(data.status); // "Your password has been reset!"

​
Success Response

{
  "status": "Your password has been reset!"
}

​
Error Responses

​
Invalid Token (422)

{
  "message": "This password reset token is invalid.",
  "errors": {
    "email": [
      "This password reset token is invalid."
    ]
  }
}

​
Validation Error (422)

{
  "message": "The password field confirmation does not match.",
  "errors": {
    "password": [
      "The password field confirmation does not match."
    ]
  }
}

​
Notes

  • Password reset tokens are single-use and expire after a configured time period
  • Upon successful password reset, a PasswordReset event is dispatched
  • The user’s remember_token is regenerated, invalidating existing “remember me” sessions
  • Password is hashed using Laravel’s Hash::make() before storage
  • After successful reset, the user must login with the new password

Build docs developers (and LLMs) love

Get started for freeTalk to us