Security

The Security settings page: adding and changing the password, and the rules it follows.

Settings → Security (/settings/security) holds the account's sign-in security. It is open to every signed-in user, whatever sign-in methods are on: the sessions list is always there, and the other cards show when their method is on (Passkeys, Two-Factor).

Account security settings in dark mode.Click to expand

Account security settings in dark mode.

The Password

The Password card shows for an account that has a password (not one that signs in only with a provider or a magic link) while AUTH_PASSWORD is on. It asks for the current password and the new one twice.

  • A correct current password and a new one that meets the requirements (Setup) change it, keep this session, sign out every other session and send "Your password was changed" to the account's address (Emails).
  • A wrong current password shows a field error under it; a new password under the requirements shows one under that. Nothing changes and no email goes out.
  • revokeOtherSessions is forced on the server (forceRevokeOtherSessions, packages/better-auth/src/password-change.ts): a direct call to /api/auth/change-password can't keep the other sessions alive.
  • The new session keeps the active organization (keepActiveOrganization, while the user is still a member); Better Auth would otherwise start it in the personal context.
  • Needs a sign-in from the last 10 minutes and is refused while impersonating (Sessions and Guards); past that, the card offers to sign in again and come back.
  • 5 tries per IP every 10 minutes, then the card asks to wait a few minutes (Rate Limits).

Adding a Password

An account without a password (it signs in with a provider, a magic link or an email code) sees an Add a password card instead, while AUTH_PASSWORD is on. It asks for the new password twice; the browser checks the requirements and that both match, and the server checks the requirements again.

  • A valid password creates the credential sign-in (the setPassword action in security.server.ts), sends "A password was added to your account" to the account's address (Emails) and reloads the page, which now shows the Password card. The other sessions stay signed in (unlike a change, no earlier password could have been taken); if the notice was not you, resetting the password signs every session out.
  • A password under the requirements shows a field error and nothing changes.
  • With AUTH_PASSWORD off the action answers 404.
  • An account that already has a password is refused with 400 PASSWORD_ALREADY_SET: nothing is overwritten.
  • auth.api.setPassword has no path, so no Better Auth hook guards it: the action calls requireAccountChange (a sign-in from the last 10 minutes, refused while impersonating), and setPassword (packages/better-auth/src/set-password.ts) applies the password policy, the per-user limit (5 tries per 10 minutes, then 429 copy; counted before the policy) and the notice.

Better Auth starts the kept session fresh after the change: it carries no user agent or IP, as Better Auth creates it without the request.

Linked Accounts

The Linked accounts card lists every configured OAuth provider (OAuth) as Linked or Link, and is hidden when there are none. The loader returns each provider's id, name and logo, whether the account has it and, if so, this account's own row id for it (what Unlink sends): never the provider account's id or tokens.

  • Link calls authClient.linkSocial (POST /api/auth/link-social) and sends the browser to the provider, which returns to the Security page.
  • The link works when the provider's email differs from the account's (allowDifferentEmails), as long as the provider has verified it. That option is read only by this flow: signing in with a provider still links only a verified, matching email, and trustedProviders stays empty.
  • When a provider account is added to an existing user (including one who signed in by email code or magic link and has no account row yet), the account's address gets "A sign-in method was added" (Emails): a link from here, or a provider sign-in that matched a verified email (OAuth). A provider sign-up, which creates the user and the account in one request, sends nothing. The rule is on the account created and on whether the user is new in that request, not on the path, so it also covers ID-token linking if you turn it on (disableIdTokenSignIn, off by default).
  • A cancel at the provider, a failure, an unverified provider email, or a provider account that belongs to another user returns with ?error=…: the card shows "Linking was cancelled", the provider's "hasn't verified this email address" copy, or one generic "We couldn't link that account" (linkErrorKey, packages/auth/src/errors.ts). Nothing is linked, and nothing names the other user.
  • callbackURL and errorCallbackURL must be paths on this site (callbackPolicy); anything else is refused with a 403 INVALID_CALLBACK_URL, not redirected. The card always sends the Security page as both, so it always returns there.
  • Unlink asks first (a confirm dialog), then calls authClient.unlinkAccount with that row id and reloads the page's data. It never removes the account's last sign-in method: with one account row left, Unlink is disabled with "Add a password or link another account first" and Better Auth refuses the call (FAILED_TO_UNLINK_LAST_ACCOUNT). Better Auth looks the row up among the signed-in user's own accounts, so another user's id is refused (ACCOUNT_NOT_FOUND) and nothing changes.
  • Link and Unlink need a sign-in from the last 10 minutes (the card offers to sign in again) and are refused while impersonating.
  • 10 link tries per IP every hour, then the card says to try again later (Rate Limits).

Active Sessions

The Where you're signed in card lists the user's unexpired sessions, one row each: browser and system (from the session's user agent, deviceOf in packages/auth/src/session-device.ts), when it started and when it was last active, and This device on the session the page is open in. A session with no (or an unrecognised) user agent shows as Unknown device: the kept session after a password change is one, as Better Auth creates it without the request.

  • The loader reads the sessions through listActiveSessions (the auth context's internalAdapter: Better Auth's /list-sessions is freshness-gated and would fail for any session older than a day) and returns, per session, only its id, the two labels, the two dates and whether it is the current one: never the session token, the IP address or the raw user agent.
  • It lists the user's own sessions only (scoped to the session's user; expired and impersonation sessions are left out). An impersonation session sees the notice and no list. After a password change on the page, the card shows only this device.
  • Sign out on a row ends that session: its next request is signed out. Sign out of all other sessions (after a confirm dialog) ends every session but this one. Both are page actions on the Security page (?revokeSession, ?revokeOtherSessions) and need a sign-in from the last 10 minutes (requireAccountChange; the card offers to sign in again) and are refused while impersonating.
  • revokeSession takes the session's id, never its token, and goes through revokeOwnSession (packages/better-auth/src/revoke-session.ts): an id that isn't one of the user's own other sessions (another user's, expired, an impersonation session, this one) answers 404 and changes nothing. This device has no Sign out button: use the account menu's sign out. revokeOtherSessions is Better Auth's auth.api.revokeOtherSessions for the session's own user: it also ends an admin's live impersonation session of this user (the page never lists those), which is accepted. Signing sessions out is not in the audit log yet except "all others" (kit.auth.sessions_revoked).

Files

FileOwnerWhat
apps/web/pages/(app)/settings/security.tsx, security.server.tsyouThe page and its loader (changePassword: the card shows)
apps/web/components/set-password-form.tsxyouThe Add a password card
packages/better-auth/src/set-password.tskitsetPassword: policy, per-user limit and notice around auth.api.setPassword
packages/auth/src/password-settings.tsxkitChangePasswordContainer: the form, through authClient.changePassword
packages/better-auth/src/password-change.tskitforceRevokeOtherSessions, passwordChanged (the notice), as Better Auth hooks
packages/auth/src/sessions-settings.tsx, session-device.tskitSessionsContainer: the rows and the Sign out buttons (callbacks from the page); deviceOf: browser and system from a user agent
packages/better-auth/src/revoke-session.tskitrevokeOwnSession: ends one of the user's own other sessions by id
packages/auth/src/linked-accounts-settings.tsxkitLinkedAccountsContainer: the providers, Link (authClient.linkSocial) and Unlink (authClient.unlinkAccount)
packages/better-auth/src/account-link.tskitaccountLinked (the notice), as a Better Auth account.create.after database hook