# Two-factor authentication
URL: https://synquic.tech/docs/guides/two-factor.md

Protect a Synq login with a code from an authenticator app. Turn it on in Settings, save your backup codes, sign in with a code, and get back in with synq reset-admin-password if the owner loses the phone.

import { Step, Steps } from 'fumadocs-ui/components/steps';

Two-factor authentication (2FA) asks for a 6-digit code from an authenticator app (1Password, Google
Authenticator, Authy, Bitwarden and others) after your password. Someone who learns your password still can't sign
in without your phone. Each person turns it on for their own account.

<Callout title="Where it applies" type="info">
2FA protects **password** sign-in. If you only sign in with GitHub or Google, the tab explains that and you turn on
two-factor with that provider instead. API tokens and MCP clients are not asked for codes: protect those by keeping
them [scoped and short-lived](/docs/security/auth#personal-access-tokens-bearer).
</Callout>

## Turn it on

<Steps>

<Step>

### Open Security & 2FA

Go to **Settings** and choose **Security & 2FA**. The **Two-factor authentication** card shows **Off**. Press
**Turn on**.

</Step>

<Step>

### Confirm your password

Type your **Current password** and press **Continue**.

</Step>

<Step>

### Scan the QR code

Scan the code with your authenticator app, or type the **Setup key** into it by hand. The entry appears in the app
as **Synq** with your email. Type the **6-digit code** the app shows and press **Verify and turn on**.

</Step>

<Step>

### Save your backup codes

Synq shows **10 backup codes**. Each one signs you in once if you can't use your authenticator. They are not shown
again: press **Copy** or **Download**, store them somewhere safe (a password manager, a printed copy), then press
**I've saved these codes**.

</Step>

</Steps>

The card now reads **On**.

## Sign in with two-factor

After your email and password, the sign-in page asks for the **Authentication code** from your app:

- Type the current 6-digit code and press **Verify**.
- Tick **Trust this device for 30 days** on your own computer to skip the code there for 30 days.
- No phone? Press **Use a backup code instead** and type one of your backup codes. Each code works once.
- Took too long? "Your sign-in timed out" means you need to enter your password again.

## Manage it

| Action | How |
| --- | --- |
| New backup codes | **New backup codes**, enter your **Current password**, then **Generate**. The old codes stop working at once. Do this when you've used several, or think someone saw them. |
| Turn it off | **Turn off**, then enter your password and a code from your authenticator (or a backup code). |
| Change phones | Turn it off on the old phone and on again with the new one, or move the entry with your authenticator app's own transfer feature. |

## Locked out

**You have a backup code:** use it at sign-in (**Use a backup code instead**), then turn 2FA off and on again to
set up your new phone, or generate new backup codes.

**You are the owner and have neither:** reset the login from the server itself. The command resets the owner's
password **and turns two-factor off** for that account, so you can sign in and set it up again. It also signs the
owner out of every browser and device:

```bash
sudo synq reset-admin-password    # on the server: asks for the new password twice
```

It needs no sign-in: it talks to the API on the server with the install's own internal key, which is why it only
works on the server. It always resets the **founding owner**, the first account created on the install. Options:

| Option | Use |
| --- | --- |
| `--password <password>` | Set the password without a prompt (8 to 128 characters). Required when there is no terminal. |
| `--email <email>` | Also change the owner's sign-in email. |
| `--name <name>` | Also change the owner's display name. |
| `--port <port>` | The API port, if the command can't find it (default: the port this install uses, else 4000). |

The reset is recorded in the [audit log](/docs/guides/audit-log).

<Callout title="Other users have no server-side reset" type="warn">
`synq reset-admin-password` only recovers the founding owner. Every other user who loses both the authenticator and
the backup codes can't get back into that account, and there is no switch in the panel to turn their 2FA off. Ask
everyone who turns on 2FA to keep their backup codes. If it happens, the owner can invite that person again with a
different email.
</Callout>

## Related guides

<Cards>
  <Card title="Teams and members" href="/docs/guides/teams-members" description="Invite people and choose their roles." />
  <Card title="Authentication" href="/docs/security/auth" description="Sessions, API tokens and MCP OAuth." />
  <Card title="Audit log" href="/docs/guides/audit-log" description="See who signed in and changed what." />
</Cards>