updateUser function parameters
The updateUser function takes an object with properties like image and name to update user information. Example: await authClient.updateUser({ image: "https://example.com/image.jpg", name: "John Doe" })
Better Auth · Concepts · all subjects
users-accounts
29 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
changeEmail feature configuration
To enable email changes, set user.changeEmail.enabled to true in the auth configuration. By default, when a user requests to change their email, a verification email is sent to the new email address and the email is only updated after verification.
sendChangeEmailConfirmation callback for current email verification
The sendChangeEmailConfirmation function can be provided to require users to confirm email changes via their current email before the verification email is sent to the new address. This function receives an object with user, newEmail, url, token properties and the request object.
updateEmailWithoutVerification setting
When user.changeEmail.updateEmailWithoutVerification is enabled, users can update their email immediately without verification if their current email is NOT verified. By default this is false, meaning email will not be updated until the new email is verified, even if the current email is unverified.
changeEmail client method usage
Use authClient.changeEmail() on the client to initiate the email change process. It takes newEmail and callbackURL parameters. Example: await authClient.changeEmail({ newEmail: "new-email@email.com", callbackURL: "/dashboard" })
Password storage location in Better Auth
A user's password is not stored in the user table. Instead, it is stored in the account table.
setPassword server-side method
The setPassword method sets a password for users registered via OAuth or other providers who don't have a credential account. It can only be called from the server. Recommended for users to go through a forgot password flow. Usage: await auth.api.setPassword({ body: { newPassword: "new-password" }, headers: await headers() })
verifyPassword server-side method
The verifyPassword function verifies a user's current password and is useful for confirming identity before sensitive operations. It can only be called from the server. Usage: await auth.api.verifyPassword({ body: { password: "user-password" }, headers: await headers() })
deleteUser feature disabled by default
The deleteUser feature is disabled by default. To enable hard deletion of users from the database, set user.deleteUser.enabled to true in the auth configuration.
sendDeleteAccountVerification callback for deletion verification
The sendDeleteAccountVerification callback sends a verification to the user before account deletion. It receives an object with user, url (pre-generated deletion link), and token properties, plus the request object. Example usage for sending email: sendEmail(data.user.email, "Verify Deletion", data.url)
deleteUser client method with callbackURL
Use authClient.deleteUser() to permanently delete a user's account. It accepts callbackURL parameter to redirect after deletion. Example: await authClient.deleteUser({ callbackURL: "/goodbye" })
deleteUser client method with token
If a custom URL was sent via sendDeleteAccountVerification callback, use authClient.deleteUser() with the token parameter to delete the user. Example: await authClient.deleteUser({ token })
deleteUser with password authentication
Users with a password can delete their account by providing the password to authClient.deleteUser(). Example: await authClient.deleteUser({ password: "password" })
session.freshAge default value for account deletion
By default, session.freshAge is set to 60 * 60 * 24 (1 day), which determines the fresh session requirement for account deletion. This can be changed in the session configuration, or set to 0 to disable freshness checks (not recommended without email verification).
beforeDelete callback for user deletion
The beforeDelete callback is called before a user is deleted and can perform cleanup or additional checks. You can throw an APIError to interrupt the deletion process. Example: throw new APIError("BAD_REQUEST", { message: "Admin accounts can't be deleted" })
afterDelete callback for user deletion
The afterDelete callback is called after a user is deleted and can perform cleanup or additional actions. Receives the user object and request.
listAccounts client method
Use authClient.listAccounts() to retrieve all accounts associated with a user. Example: const accounts = await authClient.listAccounts()
Account linking enabled by default
Account linking is enabled by default in Better Auth and lets users associate multiple authentication methods with a single account. Users can connect additional social sign-ons or OAuth providers to existing accounts if the provider confirms the user's email is verified.
Disable account linking globally
To prevent any accounts from being linked, set account.accountLinking.enabled to false in the auth configuration.
Trusted providers for forced account linking
You can specify a list of trusted providers in account.accountLinking.trustedProviders. When a user logs in using a trusted provider, their account will be automatically linked even if the provider doesn't confirm email verification. Use with caution as it increases account takeover risk.
Disable implicit account linking
Set account.accountLinking.disableImplicitLinking to true to prevent automatic linking when a user signs in with an OAuth provider whose email matches an existing user. With this enabled, same-email OAuth sign-ins for existing users are rejected with the account_not_linked error instead of being silently linked. New users can still sign up via OAuth, and authenticated users can still link explicitly via linkSocial().
linkSocial client method
Use authClient.linkSocial() to link a social provider to a signed-in user's account. Takes provider and callbackURL parameters. Example: await authClient.linkSocial({ provider: "google", callbackURL: "/callback" })
linkSocial with custom scopes
When using linkSocial, you can request specific scopes different from initial authentication scopes. Example: await authClient.linkSocial({ provider: "google", callbackURL: "/callback", scopes: ["https://www.googleapis.com/auth/drive.readonly"] })
linkSocial with ID token
Link accounts using ID tokens directly without redirecting to the provider's OAuth flow. Useful when you already have valid tokens from the provider (e.g., after signing in with native SDK or mobile app). Example: await authClient.linkSocial({ provider: "google", idToken: { token: "id_••••••er", nonce: "nonce_used_for_token", accessToken: "access_token", refreshToken: "refresh_token" } })
allowDifferentEmails for account linking
Enable account.accountLinking.allowDifferentEmails to true to allow users to link a social account with a different email address than the user, or to use a provider that does not return email addresses.
updateUserInfoOnLink setting
Set account.accountLinking.updateUserInfoOnLink to true to copy the provider's profile to the user each time an account is linked. Synced fields are name, image, and any input-allowed fields from mapProfileToUser. The user's email and emailVerified are never changed on link.
Link credential-based accounts
To link a credential-based account (e.g., email and password) to an existing user, use the setPassword method on the server. Users can also initiate a forgot password flow. Example: await auth.api.setPassword({ body: { newPassword: "new-password" }, headers: await headers() })
unlinkAccount client method
Use authClient.unlinkAccount() to unlink a user account by providing a providerId. Optionally specify accountId to unlink a specific account. Example: await authClient.unlinkAccount({ providerId: "google" }) or await authClient.unlinkAccount({ providerId: "google", accountId: "123" })
Account unlinking prevents account lockout
By default, if a user only has one account, unlinking is prevented to stop account lockout. To allow unlinking all accounts, set account.accountLinking.allowUnlinkingAll to true.