Account security

Two-factor sign-in, passkeys, organizations’ security policies and password reset links. The decisions and their reasons are in ADR 0053.

For a person

• Authenticator app. Account → Sign-in security → set up with the password: scan the QR code (or type the key) into an authenticator app, save the ten recovery codes shown once, and confirm with a code. A password sign-in then asks for a code, or a recovery code; each recovery code works once. “Remember this browser” skips the code on that browser for at most 30 days, unless an organization’s policy refuses remembered browsers. Recovery codes are regenerated, and two-factor is turned off, with the password.
• Passkeys. Account → Sign-in security → add a passkey (Face ID, Touch ID, Windows Hello, a security key or a phone). “Sign in with a passkey” then needs no e-mail address or password. Passkeys are renamed and removed from the same list. They need HTTPS (or localhost) and a host name, and work only on the base URL’s host and its subdomains. Another address trusted for sign-in (installation settings), an IP address or plain HTTP offers no passkey: sign-in works there with a password and a code, the security screen lists the address under “Passkeys unavailable on”, and a member who must use a passkey is pointed to the base URL.
• Once you have a second factor, changing your factors asks you to prove one first.

For an organization’s owners and administrators

Organizations → Organization security (a link on each organization you own or administer):

• Sign-in policy. Require nothing, a second factor, or a passkey; a grace period (0–90 days, counted from the change or a member’s joining, whichever is later); whether a remembered browser counts; a maximum session age (1–720 hours). After the grace period, a member whose session does not meet the requirement is asked for the missing factor when they enter the organization (the “Verify it is you” page), and can set it up from their account; their phone must be signed in again.
• Members. Every member’s factors and status (compliant, within the grace period, overdue), and the API keys and organization tokens created by members who do not comply, to revoke them.
• Reset links. Create reset link makes a one-time link for a member of a lower role (owners for administrators and members, administrators for members); copy it and send it to them; it works once, for 60 minutes. A member who also belongs to another organization, or administers the instance, is reset by an instance administrator from the command line (instance administrators).

For integrations

Problem	Status	When
auth.step_up_required	403	A browser session must prove requirement (second_factor or passkey) before it acts in organization_id.
auth.reauthentication_required	401	A device token was paired by a session that no longer meets its organization’s policy, or is older than its session age.
password_reset.invalid	400	Every unusable reset link.
password_reset.rate_limited	429	A reset budget is spent; see Retry-After.

API keys, organization tokens and client sessions are not sign-ins: no policy challenges them. The identity routes are Better Auth’s under /api/auth (see ADR 0053 for the exact list); the administration is accountSecurity.* in the SDK.