Password Reset

AutoCom provides a secure password reset flow using email-based tokens that expire after 60 minutes.

Overview

The password reset process has three steps:

1. Request reset link - User provides their email
2. Verify token - Frontend verifies the token is valid
3. Reset password - User sets a new password

API Endpoints

Request Password Reset

Send a password reset link to the user's email address.

POST /api/v1/auth/forgot-password
X-Tenant: your-tenant-id
Content-Type: application/json

{
  "email": "user@example.com"
}

Response (always returns success to prevent email enumeration):

{
  "message": "If an account exists with this email, you will receive a password reset link."
}

Verify Reset Token

Validate that a reset token is still valid before showing the reset form.

POST /api/v1/auth/verify-reset-token
X-Tenant: your-tenant-id
Content-Type: application/json

{
  "email": "user@example.com",
  "token": "abc123..."
}

Success response:

{
  "message": "Token is valid",
  "email": "user@example.com"
}

Error response (invalid/expired token):

{
  "message": "The given data was invalid.",
  "errors": {
    "token": ["This password reset token is invalid."]
  }
}

Reset Password

Set a new password using a valid reset token.

POST /api/v1/auth/reset-password
X-Tenant: your-tenant-id
Content-Type: application/json

{
  "email": "user@example.com",
  "token": "abc123...",
  "password": "new_secure_password",
  "password_confirmation": "new_secure_password"
}

Success response:

{
  "message": "Password has been reset successfully. Please log in with your new password."
}

Email Template

The password reset email includes:

• Organization name (from tenant context)
• Reset link with token
• 60-minute expiration notice
• Security warning

Example reset URL format:

https://app.autocom.example.com/auth/reset-password?token=abc123&email=user@example.com&tenant=tenant-id

Security Considerations

Token Security

• Tokens are stored hashed using bcrypt
• Only one active token per user (previous tokens deleted)
• 60-minute expiration
• Single-use (deleted after successful reset)

Password Requirements

• Minimum 8 characters
• Must be confirmed (password_confirmation)
• Cannot be the same as the reset token

Session Invalidation

After a successful password reset:

• All existing access tokens are revoked
• User must log in with the new password
• Activity log entry is created

Frontend Integration

Reset Request Page

async function requestPasswordReset(email: string, tenantId: string) {
  const response = await fetch('/api/v1/auth/forgot-password', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Tenant': tenantId,
    },
    body: JSON.stringify({ email }),
  });

  return response.json();
}

Reset Form Page

async function resetPassword(
  email: string,
  token: string,
  password: string,
  tenantId: string
) {
  const response = await fetch('/api/v1/auth/reset-password', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Tenant': tenantId,
    },
    body: JSON.stringify({
      email,
      token,
      password,
      password_confirmation: password,
    }),
  });

  if (response.ok) {
    // Redirect to login
    window.location.href = '/login';
  }

  return response.json();
}

Activity Logging

Password reset events are logged for security auditing:

Action	Description
password_reset_requested	User requested a reset link
password_changed	Password was successfully reset

View security events in the Activity Logs with the via: reset_link metadata.