# Password and Passkey Recovery

This guide helps administrators recover access to their Wizarr instance when locked out due to forgotten passwords or lost passkeys.

## Recovery Tool Overview

The recovery tool is a command-line utility designed to help administrators regain access when locked out. It provides emergency recovery options for common authentication issues.

### Key Features

* **Password Reset**: Reset passwords for admin accounts
* **Passkey Management**: Remove all passkeys for specific admin accounts
* **Emergency Admin**: Create emergency admin accounts
* **Account Listing**: View all admin accounts and their passkey status
* **Container-Friendly**: Designed to work seamlessly in Docker containers

## When to Use the Recovery Tool

Use the recovery tool in these situations:

* **Forgotten Password**: You cannot remember your admin password
* **Lost Passkey**: Your passkey device is lost or broken
* **2FA Lockout**: You're locked out due to passkey 2FA requirements
* **Complete Lockout**: All admin accounts are inaccessible

## Running the Recovery Tool

### Docker Container

For Docker installations:

```bash
# Find your container name
docker ps

# Run it directly
docker exec -it <container_name> uv run recovery_tool.py
```

## Recovery Options

The recovery tool provides five main options:

### 1. List All Admin Accounts

View all administrators and their current status:

* Username and ID
* Number of registered passkeys
* Account creation date
* Legacy admin status

### 2. Reset Admin Password

Change the password for any admin account:

1. Select the admin account from the list
2. Enter a new password (minimum 6 characters)
3. Confirm the password
4. The password is immediately updated

### 3. Remove All Passkeys

Delete all passkeys for a specific admin account:

1. Select the admin account
2. Confirm the operation (this cannot be undone)
3. All passkeys are removed
4. 2FA requirement is disabled for that account

### 4. Create Emergency Admin

Create a new admin account with password authentication:

1. Enter a username (must be unique)
2. Set a password (minimum 6 characters)
3. Confirm the password
4. New admin account is created immediately

### 5. Exit

Close the recovery tool safely.

## Common Recovery Scenarios

### Scenario 1: Forgotten Admin Password

**Problem**: You remember your username but forgot your password.

**Solution**:

1. Run the recovery tool
2. Select option 2 (Reset admin password)
3. Choose your admin account
4. Enter a new password
5. Log in with the new password

### Scenario 2: Lost Passkey Device

**Problem**: Your passkey device is lost, broken, or unavailable.

**Solution**:

1. Run the recovery tool
2. Select option 3 (Remove all passkeys for admin)
3. Choose your admin account
4. Confirm the removal
5. Log in with username/password (2FA disabled)

### Scenario 3: Complete Lockout

**Problem**: All admin accounts are inaccessible.

**Solution**:

1. Run the recovery tool
2. Select option 4 (Create emergency admin account)
3. Create a new admin account
4. Log in with the emergency account
5. Manage other accounts through the web interface
6. Delete the emergency account when no longer needed

### Scenario 4: 2FA Lockout

**Problem**: You're locked out due to passkey 2FA requirements.

**Solution**:

1. Run the recovery tool
2. Select option 3 (Remove all passkeys for admin)
3. Choose your admin account
4. Confirm passkey removal
5. Log in with username/password only

## Security Considerations

{% hint style="warning" %}
**Important Security Notes**

* Only run this tool when you have direct access to the server/container
* The tool requires database access and should only be used by system administrators
* Anyone with server access can use this tool to gain admin privileges
  {% endhint %}

### After Recovery

Once you regain access, consider these security steps:

1. **Update Passwords**: Change passwords for all admin accounts
2. **Re-register Passkeys**: Set up new passkeys for 2FA
3. **Review Admin Access**: Audit who has admin privileges
4. **Delete Emergency Accounts**: Remove temporary accounts when no longer needed
5. **Secure Server Access**: Ensure only authorized personnel can access the server

## System Requirements

The recovery tool requires:

* Access to the server or container running Wizarr
* Read/write access to the database
* Proper Flask environment configuration
* Python execution privileges

## Environment Configuration

The tool automatically uses your existing Wizarr configuration. Ensure these environment variables are set if needed:

* `DATABASE_URL` - Database connection string
* `FLASK_ENV` - Flask environment (development/production)
* `SECRET_KEY` - Flask secret key

## Troubleshooting

### Common Issues

**Import Error**

* Ensure you're running the tool from the Wizarr root directory
* Check that all dependencies are installed

**Database Connection Error**

* Verify the database is accessible
* Check that the Flask environment is properly configured

**Permission Error**

* Ensure you have write access to the database
* Check file permissions on the database file

### Tool Output

The recovery tool provides clear feedback:

* ✅ Success messages for completed operations
* ❌ Error messages for failed operations
* ⚠️ Warning messages for destructive operations
* ℹ️ Information messages for status updates

## Best Practices

1. **Regular Backups**: Keep database backups before making changes
2. **Test Access**: Verify you can log in after making changes
3. **Document Changes**: Keep records of recovery actions taken
4. **Secure Storage**: Store recovery procedures in a secure location
5. **Regular Reviews**: Periodically review admin account access

## Support

If you encounter issues with the recovery tool:

1. Check the troubleshooting section above
2. Verify database connectivity
3. Ensure proper permissions
4. Review Flask application logs for additional details
5. Contact support through the official channels

{% hint style="info" %}
**Remember**: This tool is for emergency recovery only. Regular admin management should be done through the web interface.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wizarr.dev/using-wizarr/password-passkey-recovery.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.