Self-service password change
A signed-in user updates their password from account settings.
Better Auth · Module
changePassword
Changes the authenticated user's password using the current password and a new password. It can optionally invalidate the user's other active sessions.
How it works
Call the client method with the user's current password and the replacement password. Set revokeOtherSessions to true when all other active sessions should be invalidated; the server-side API alternative requires session cookies.
Syntax
authClient.changePassword({ newPassword, currentPassword, revokeOtherSessions? })Parameters
| Name | Type | Description |
|---|---|---|
newPassword | string | The new password to set; required. |
currentPassword | string | The current user password; required. |
revokeOtherSessions | boolean | Invalidates all other active sessions when true. |
Returns
The documentation shows the returned data/error result for the client call; the server example returns the API result.
Key points
- Better Auth documents both a client call and a server API approach for changing a user's password.
- newPassword contains the replacement password and is required.
- currentPassword contains the existing password and is required for the change.
- Set revokeOtherSessions to true to terminate the user's other active sessions after changing the password.
Common mistakes
- The server API must be used for server-only invocation; do not treat the client method as a server-side function.
- The server-side endpoint depends on session cookies, so the request must carry the authenticated session.
Example: Change a user's password
import { authClient } from "@/lib/auth-client";
const { data, error } = await authClient.changePassword({
newPassword: "new-password-123",
currentPassword: "current-password-123",
revokeOtherSessions: true,
});
if (error) throw error;
console.log(data);Changes the signed-in user's password and optionally invalidates the user's other active sessions.
When to use it
Invalidate other sessions
A password update should sign out the account everywhere else.
Server-side password update
A server action or API handler changes the password for an authenticated session.
Interview questions
QHow does the client password-change operation work?
Use authClient.changePassword with newPassword and currentPassword. The optional revokeOtherSessions flag invalidates every other active session when enabled.
Follow-up: How would you force this from server code? Use auth.api.changePassword with a body containing the password fields and pass session cookies in the request headers.
QWhat arguments does changePassword accept?
newPassword is the replacement password and currentPassword is the user's existing password; both are required. revokeOtherSessions is optional and controls whether other active sessions are invalidated.
Follow-up: What security context is needed by the server endpoint? An authenticated session represented by session cookies is required.
QHow do you invoke the server-side variant?
The server endpoint is POST /change-password and is called with auth.api.changePassword. Its request body contains the password values and optional session-revocation flag, while headers provide the session cookies.
Follow-up: When should session revocation be enabled? Enable it when changing the password should terminate the user's other active sessions.
Related
auth.api.changePasswordsetPasswordrequestPasswordResetresetPasswordrevokeOtherSessions