---
title: "HitKeep Account Recovery for Lost MFA | HitKeep"
description: "Recover a HitKeep account after lost MFA by using recovery codes, owner-only dashboard reset, or offline CLI break-glass recovery."
canonical: "https://hitkeep.com/guides/security/recovery/"
---

# HitKeep Account Recovery for Lost MFA

A user has lost their authenticator app, their passkey device, or their phone and can no longer complete MFA. HitKeep now supports three recovery paths, depending on what access remains available.

## Choose the Right Recovery Path

### 1. User still knows their password and has recovery codes

This is the preferred self-service path.

1. Go to the normal login page.
2. Enter the account email address and password.
3. On the MFA screen, choose **Use recovery code**.
4. Enter one unused recovery code.

Each recovery code can be used once. After login, generate a new set under **Settings → Security** if the old set may be exposed or mostly consumed.

### 2. Another instance owner can still sign in

This is the preferred operator path for shared instances and cloud deployments.

1. Sign in as an instance owner.
2. Open **Administration → Users**.
3. Find the locked-out user.
4. Use **Disable MFA**.

This owner-only action removes TOTP, passkeys, active recovery codes, and remember-me sessions for the target account. The user can then log in again with email and password and re-enroll MFA.

### 3. No owner can sign in

This is the break-glass path. Use the offline `recover disable-2fa` CLI command directly against the HitKeep database.

Caution

The `recover` command opens the DuckDB database directly and **requires HitKeep to be stopped first**. Running it against a live instance will fail — DuckDB only allows one writer at a time.

The `--db` flag defaults to `hitkeep.db` in the working directory. Pass it explicitly if your database lives elsewhere (e.g. `/var/lib/hitkeep/data/hitkeep.db`).

## Offline Recovery Steps

- systemd
- Docker
- Manual process

```
sudo systemctl stop hitkeep
```

Then run the recovery command and restart:

```
hitkeep recover disable-2fa \
  --email locked-user@example.com \
  --db /var/lib/hitkeep/data/hitkeep.db

sudo systemctl start hitkeep
```

Stop the running container, then spin up a temporary container with the same image and data volume to run the recovery command, then restart normally:

```
# 1. Stop the running container
docker stop hitkeep

# 2. Run recovery in a temporary container against the same volume
docker run --rm \
  -v hitkeep-data:/var/lib/hitkeep/data \
  ghcr.io/pascalebeier/hitkeep:latest \
  recover disable-2fa \
    --email locked-user@example.com \
    --db /var/lib/hitkeep/data/hitkeep.db

# 3. Start the container again
docker start hitkeep
```

With Docker Compose:

```
docker compose stop hitkeep

docker compose run --rm hitkeep \
  recover disable-2fa \
    --email locked-user@example.com \
    --db /var/lib/hitkeep/data/hitkeep.db

docker compose start hitkeep
```

```
pkill hitkeep

hitkeep recover disable-2fa \
  --email locked-user@example.com \
  --db /path/to/hitkeep.db

hitkeep -db /path/to/hitkeep.db
```

## After Recovery

Advise the user to:

1. Log in with their existing password.
2. Generate a fresh set of recovery codes under **Settings → Security**.
3. Re-enroll TOTP or passkeys under **Settings → Security**.
4. If their password may also be compromised, change it under **Settings → Security → Change Password**.

## Operational Guidance

- Use recovery codes for owner self-recovery.
- Keep at least two instance owners on production deployments.
- Treat the offline CLI as break-glass only.
- The offline `recover disable-2fa` command clears TOTP, passkeys, active recovery codes, and remember-me sessions.

## Related

- [Two-Factor Authentication](https://hitkeep.com/guides/security/two-factor-authentication/)
- [Permissions & Roles](https://hitkeep.com/guides/admin/permissions/)
- [Configuration Reference](https://hitkeep.com/reference/configuration/)

Need a self-service account recovery flow with identity verification? [HitKeep Cloud →](https://cloud.hitkeep.eu/signup?plan=free&billing=monthly&utm_source=hitkeep_docs&utm_medium=referral&utm_campaign=cloud_signup&utm_content=docs_inline) includes automated, audited recovery workflows.

[Previous Two-factor authentication](https://hitkeep.com/guides/security/two-factor-authentication/)[Next Verifying artifacts](https://hitkeep.com/guides/security/verify-artifacts/)