Account Recovery

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

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

Docker

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

Manual process

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
• Permissions & Roles
• Configuration Reference

Need a self-service account recovery flow with identity verification? HitKeep Cloud → includes automated, audited recovery workflows.