# Security

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

*Canonical: https://makerkit.dev/docs/void-cloudflare/account/security*

---

**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](../authentication/passkeys), [Two-Factor](../authentication/two-factor)).

{% img src="/assets/images/docs/void-cloudflare/security.png" width="1440" height="900" alt="Account security settings in dark mode." /%}

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](../authentication/setup)) change it, **keep this session**, sign out every other session and send "Your password was changed" to the account's address ([Emails](../authentication/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](../authentication/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](../authentication/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](../authentication/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](../authentication/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](../authentication/emails)): a link from here, or a provider sign-in that matched a verified email ([OAuth](../authentication/oauth#account-linking)). 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](../authentication/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

| File | Owner | What |
|---|---|---|
| `apps/web/pages/(app)/settings/security.tsx`, `security.server.ts` | you | The page and its loader (`changePassword`: the card shows) |
| `apps/web/components/set-password-form.tsx` | you | The Add a password card |
| `packages/better-auth/src/set-password.ts` | kit | `setPassword`: policy, per-user limit and notice around `auth.api.setPassword` |
| `packages/auth/src/password-settings.tsx` | kit | `ChangePasswordContainer`: the form, through `authClient.changePassword` |
| `packages/better-auth/src/password-change.ts` | kit | `forceRevokeOtherSessions`, `passwordChanged` (the notice), as Better Auth hooks |
| `packages/auth/src/sessions-settings.tsx`, `session-device.ts` | kit | `SessionsContainer`: 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.ts` | kit | `revokeOwnSession`: ends one of the user's own other sessions by id |
| `packages/auth/src/linked-accounts-settings.tsx` | kit | `LinkedAccountsContainer`: the providers, Link (`authClient.linkSocial`) and Unlink (`authClient.unlinkAccount`) |
| `packages/better-auth/src/account-link.ts` | kit | `accountLinked` (the notice), as a Better Auth `account.create.after` database hook |
