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.dart

Dart

await Koolbase.auth.forgotPassword(
  email: '[email protected]',
);
// 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.

Deep linking the reset email

The link in the reset email points wherever you configure your project's Password Reset URL under Email Branding in the dashboard. Koolbase substitutes {token} with the actual token at send time.

Common URL patterns

Universal Link (recommended for production)
  https://yourdomain.com/reset?token={token}

Custom scheme (simpler, dev-friendly)
  myapp://reset?token={token}

Universal Links vs custom schemes

Universal Links (iOS) and App Links (Android) are https URLs your app claims via apple-app-site-association and assetlinks.json hosted on your domain. They open your app when installed and fall back to a web page when it isn't — the right choice for production.

Custom schemes like myapp:// are not clickable in most mail clients, including Gmail — the button renders but does nothing, which looks exactly like a delivery failure. Don't ship them to real users. For production use an https Universal Link / App Link, ...or leave the template blank for the Koolbase-hosted https reset page, which works in every mail client with no app-side setup. See Deep Linking Auth Emails for the full setup.

Without a configured URL

If you don't set a Password Reset URL in the dashboard, the link in the email falls back to a Koolbase dashboard URL that won't reach your app. Configure this before going to production.

When the user taps the link, your deep link handler extracts the token query parameter and passes it to resetPassword() — same code path regardless of which link mechanism you chose. See the next section.

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.dart

Dart

// 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. An expired or tampered link makes resetPassword() throw a KoolbaseAuthException with code invalid_token. A new password under 8 characters throws WeakPasswordException; the link is still good, so let the user retype rather than request another email.

Using a link does two more things. It marks the email as verified, since clicking a link sent to an inbox proves the person owns it. And it cancels every other reset or invitation link still outstanding for that account, so an older email can't be used afterwards.

lib/auth.dart

Dart

try {
  await Koolbase.auth.resetPassword(token: token, newPassword: newPassword);
} on WeakPasswordException {
  showError('Use at least 8 characters.');
} on KoolbaseAuthException catch (e) {
  if (e.code == 'invalid_token') {
    showError('This reset link is invalid or has expired. Please request a new one.');
  }
}

Change password while signed in

For a settings screen, where the user knows their current password and is already signed in. No email involved. The current password is verified first; on success every other session for that user is signed out, and the device that made the change stays in.

lib/settings.dart

Dart

try {
  await Koolbase.auth.changePassword(
    currentPassword: currentController.text,
    newPassword: newController.text,
  );
  showSuccess('Password changed. Other devices have been signed out.');
} on InvalidPasswordException {
  showError('Current password is incorrect.');
} on WeakPasswordException {
  showError('Use at least 8 characters.');
}

OAuth-only accounts

An account that signed up with Google or Apple and never set a password has nothing to change. changePassword() throws InvalidPasswordException for these, the same as a wrong current password, so a caller cannot use it to probe which sign-in methods an account has.