Password Reset - Modelence

Modelence provides a secure password reset flow with email tokens.

The reset email delivery setup below (provider, sender, template, redirect URL) is configured under the email: key of startApp. To run code on related auth events, register callbacks under auth: — see Auth Hooks.

Configuration

Configure password reset emails in your server setup:

import { startApp } from 'modelence/server';
import resendProvider from '@modelence/resend';

startApp({
  email: {
    provider: resendProvider,
    from: 'noreply@yourdomain.com',
    passwordReset: {
      subject: 'Reset your password',
      redirectUrl: 'https://yourdomain.com/reset-password',
    },
  },
});

redirectUrl is the page in your app where the user enters their new password. Modelence redirects here after validating the token and storing it in an httpOnly cookie, so this URL never carries the token. This is also where you call resetPassword({ password }).

How It Works

User requests a password reset by providing their email
A secure reset token is generated, hashed, and stored in the database (only the hash is stored, never the raw token)
An email with a reset link is sent to the user
The link points at a Modelence server route, not your SPA page. That route validates the token, stores it in a short-lived httpOnly cookie, and redirects to your configured redirectUrl without the token in the URL
On that page, the user enters their new password and you call resetPassword({ password }) — the token is read server-side from the cookie, so it never reaches client JavaScript
Password is updated and the token is invalidated (single-use)
If the user’s email was not yet verified, it is automatically marked as verified

Since the user must receive the reset email to complete the flow, a successful password reset proves ownership of the email address.

The reset token never reaches your client code or appears in a browser URL — it is exchanged server-side through an httpOnly cookie. This closes the window where a token could leak via the address bar, browser history, or the Referer header.

The token cookie is sent with credentialed requests, so it works even when your SPA and Modelence API are on different origins. For that cross-origin case, the API must respond with Access-Control-Allow-Credentials: true and a specific (non-wildcard) allowed origin, otherwise the browser drops the cookie and the reset fails.

Base URL requirement

The reset email link is built from your site’s base URL, so you must set it via the _system.site.url config (or the MODELENCE_SITE_URL environment variable). If it isn’t set, sending a reset token fails with a clear error rather than emailing a broken link.

Client Implementation

Request Password Reset

import { sendResetPasswordToken } from 'modelence/client';

async function handleForgotPassword(email: string) {
  try {
    await sendResetPasswordToken({ email });
    console.log('Password reset email sent');
  } catch (error) {
    console.error('Error:', error.message);
  }
}

Reset Password

The user lands on your redirectUrl page after clicking the email link. The token is already held in an httpOnly cookie, so you only collect the new password — don’t pass a token:

import { resetPassword } from 'modelence/client';

async function handleResetPassword(newPassword: string) {
  try {
    await resetPassword({ password: newPassword });
    console.log('Password reset successful');
  } catch (error) {
    console.error('Reset failed:', error.message);
  }
}

Passing a token to resetPassword({ token, password }) is deprecated. It exists only for legacy flows that still carry the token client-side and will be removed. New apps should rely on the server-side cookie exchange and submit just the password.

Custom Reset Email Template

startApp({
  email: {
    provider: resendProvider,
    from: 'noreply@yourdomain.com',
    passwordReset: {
      subject: 'Reset Your Password',
      template: ({ name, email, resetUrl }) => `
        <html>
          <body>
            <h1>Password Reset Request</h1>
            <p>Hi ${name || 'there'},</p>
            <p>We received a request to reset your password. Click the button below to proceed:</p>
            <a href="${resetUrl}"
               style="background-color: #5509D9; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; display: inline-block;">
              Reset Password
            </a>
            <p>If you didn't request this, you can safely ignore this email.</p>
            <p>This link will expire in 1 hour.</p>
          </body>
        </html>
      `,
      redirectUrl: 'https://yourdomain.com/reset-password',
    },
  },
});

​Configuration

​How It Works

​Base URL requirement

​Client Implementation

​Request Password Reset

​Reset Password

​Custom Reset Email Template

Configuration

How It Works

Base URL requirement

Client Implementation

Request Password Reset

Reset Password

Custom Reset Email Template