Password Management
Forget, reset, change, and set passwords.
The PasswordManagementPlugin provides endpoints for password reset flows and password changes.
Setup
use better_auth::plugins::PasswordManagementPlugin;
let auth = BetterAuth::new(config)
.database(database)
.plugin(
PasswordManagementPlugin::new()
.reset_token_expiry_hours(24)
.require_current_password(true)
)
.build()
.await?;Plugin Options
| Option | Type | Default | Description |
|---|---|---|---|
reset_token_expiry_hours | i64 | 24 | Hours before reset token expires |
require_current_password | bool | true | Require current password for changes |
send_email_notifications | bool | true | Send email on password changes |
Forget Password
Initiates a password reset flow. Requires an email provider to send the reset link.
POST /forget-password
Content-Type: application/json{
"email": "alice@example.com",
"redirectTo": "https://example.com/reset"
}Response
{
"status": true
}Always returns success regardless of whether the email exists (prevents enumeration).
Reset Password
Completes the password reset using a token from the email link.
POST /reset-password
Content-Type: application/json{
"newPassword": "new_secure_password",
"token": "reset_token_from_email"
}Response
{
"user": { ... }
}| Status | Condition |
|---|---|
| 400 | Token missing or expired, password too short |
Validate Reset Token
Check if a reset token is still valid before showing the reset form.
GET /reset-password/{token}Returns 200 if valid, 400 if expired or invalid.
Change Password (Authenticated)
Change password for the currently signed-in user.
POST /change-password
Authorization: Bearer <token>
Content-Type: application/json{
"currentPassword": "old_password",
"newPassword": "new_password",
"revokeOtherSessions": "true"
}| Field | Required | Description |
|---|---|---|
currentPassword | Yes | Current password for verification |
newPassword | Yes | New password (must meet policy) |
revokeOtherSessions | No | Revoke all other sessions after change |
Response
{
"user": { ... },
"token": "session_new..."
}Set Password (Authenticated)
Set a password for users who signed up via OAuth and don't have one yet.
POST /set-password
Authorization: Bearer <token>
Content-Type: application/json{
"newPassword": "new_password"
}Returns 400 if the user already has a password set.