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.

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:// need no domain setup but have no web fallback, and some mail clients strip them. Fine for development or internal builds.

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.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.');
  }
}