# Sign-in and two-factor

URL: https://docs.vaultpanel.net/guides/security/sign-in-and-two-factor

> Protect panel accounts with two-factor sign-in and recovery codes, require it by policy, manage signed-in sessions and understand lockout and rate limits.

Panel accounts sign in with an email address and a password, and optionally a code from an authenticator app. Owners and admins can require two-factor sign-in for some or all accounts, see every signed-in browser and end sessions.

## Passwords

- Passwords need at least 12 characters and are stored as scrypt hashes.
- A failed sign-in takes the same time whether or not the account exists.
- Changing your password under **Account** signs you out everywhere else.

### Forgotten passwords

When [panel email](https://docs.vaultpanel.net/guides/dns-and-email/panel-email) is set up, the sign-in page offers **Forgot your password?** and emails a reset link, at most once every 5 minutes per account. Without panel email, ask an owner or admin: with `users.manage` they can click **Create password reset link** on your account under **Users**. Reset links work once and expire after 2 hours.

## Two-factor sign-in

Two-factor sign-in uses time-based one-time codes (TOTP, RFC 6238) from an app such as 1Password, Authy or Google Authenticator. The secret is encrypted at rest, and a code cannot be used twice.

### Turn it on

### Start the setup

Open **Account** from the account menu. Under **Two-factor sign-in**, click **Set up two-factor sign-in**.

### Add the account to your app

Add it with the **Setup key**, or click **Open in authenticator app** on a phone that has one.

### Confirm a code

Enter the six-digit **Code from the app** and click **Turn on**.

### Save your recovery codes

The panel shows 10 one-time recovery codes, such as `7kq3m-x9t2p`. **Copy** or **Download** them now: they are not shown again.

From then on, signing in asks for a code after your password. If you lose your app, choose **Lost your app? Use a recovery code**. Each recovery code works once, using one is recorded in the audit log, and **Account** shows how many are left.

- **Make new codes** replaces all your recovery codes. It asks for your password and a current code.
- **Turn off two-factor sign-in** also asks for your password and a current code.

Someone who lost both their app and their recovery codes needs an owner or admin with `users.manage` to click **Turn off two-factor sign-in** on their account under **Users**, or under **Security > Authentication**. That account is signed out everywhere.

### Require it for everyone

**Security > Authentication** sets the two-factor policy. It needs `settings.manage` (owners and admins).

| Policy | Who must use two-factor sign-in |
| --- | --- |
| **Optional** | Each person decides |
| **Owners and admins** | Owners and admins |
| **Everyone** | Every account |

You must use two-factor sign-in yourself before you can require it; otherwise saving fails with `TWO_FACTOR_REQUIRED_FIRST`. The policy applies at once: someone it covers who has not set it up can only set it up, or sign out, until they do. Agents and webhooks are not affected.

The **People** list on the same page shows each account's role, two-factor state, active sessions and last sign-in.

> **Note:**
One-time sign-in links that a [billing system](https://docs.vaultpanel.net/guides/hosting-and-billing/billing-api) requests for a hosting customer skip the second factor, because the billing system's key can already set that account's password. Each link works once, within two minutes.

## Sessions

A session lasts 12 hours by default (`VAULTPANEL_SESSION_TTL_HOURS`, from 1 hour to 30 days). Session cookies are `HttpOnly`, `SameSite=Strict` and, in production, `Secure`. Changing a password, role or active state ends that person's sessions.

- **Account > Where you're signed in** lists your browsers. Sign out one you no longer use, or **Sign out everywhere else**. If you see one you don't recognise, sign it out and change your password.
- **Security > Authentication > Signed-in browsers** lists everyone's active sessions. With `users.manage` you can end any of them, except those of people whose role is above yours.

## Rate limits and lockout

| What | Limit |
| --- | --- |
| Failed sign-ins on one account | 5, then the account is locked for 15 minutes (`ACCOUNT_LOCKED`) |
| Sign-in attempts per IP address | 20 per 15 minutes |
| Owner setup attempts per IP address | 10 per 15 minutes |
| Password reset requests per IP address | 20 per 15 minutes |
| API requests per IP address | 600 per minute |

Requests over a limit get `429` with the code `RATE_LIMITED`. The limits are kept in memory by each panel process.

## Audit log

Sign-ins and changes to them are recorded in the [audit log](https://docs.vaultpanel.net/guides/security/audit-log), including `auth.login` (with failures and their reason), `auth.logout`, `auth.password_change`, `auth.password_reset_request`, `auth.recovery_codes_regenerate`, `auth.session_revoke`, `user.session_revoke` and `security.two_factor_policy`.
