Password Reset

Let users securely reset their password using a time-limited token sent to their email.

How it works

User requests a reset — your app calls forgotPassword(email)

Koolbase sends a one-time reset token to the user's email (expires in 1 hour)

User opens the link — your app receives the token from the deep link

Your app shows a new password form and calls resetPassword(token, newPassword)

Password is updated — all existing sessions are invalidated

Request a reset

Call when the user submits the forgot password form:

lib/auth.dartDart

await Koolbase.auth.forgotPassword(
  email: 'user@example.com',
);
// Always succeeds — even if the email doesn't exist
// (prevents user enumeration)

Security note

The forgotPassword() call always returns success regardless of whether the email exists in the system. This prevents attackers from using the endpoint to enumerate registered email addresses.

Reset the password

When the user clicks the link in their email, your app receives the token via deep link. Show a new password form, then call resetPassword():

lib/auth.dartDart

// token comes from your deep link handler
final token = Uri.parse(incomingLink).queryParameters['token'];

await Koolbase.auth.resetPassword(
  token: token!,
  newPassword: 'newSecurePassword123',
);

// All previous sessions are now invalid
// User must log in again
Navigator.pushNamedAndRemoveUntil(context, '/login', (_) => false);

Token expiry

Reset tokens expire after 1 hour. If the token has expired, resetPassword() will throw a KoolbaseAuthException with code token_expired.

lib/auth.dartDart

try {
  await Koolbase.auth.resetPassword(token: token, newPassword: newPassword);
} on KoolbaseAuthException catch (e) {
  if (e.code == 'token_expired') {
    showError('This reset link has expired. Please request a new one.');
  } else if (e.code == 'token_invalid') {
    showError('Invalid reset link.');
  }
}