Two-Factor Authentication & App Passwords — User Guide

Electric Monk uses Authentik for identity and access management. You can strengthen your account security by enabling TOTP (Time-Based One-Time Passwords) as a second factor. This guide walks you through setting up TOTP and generating app passwords for email clients that don't support interactive two-factor prompts.

What You'll Need

• A smartphone or tablet with an authenticator app installed:
  • Google Authenticator (iOS / Android)
  • Authy (iOS / Android)
  • Microsoft Authenticator, 1Password, Bitwarden, or any TOTP-compatible app
• Your existing Authentik username and password

Part 1 — Setting Up TOTP in Authentik

Step 1: Open Your Authentik User Settings

1. Go to auth.electricmonk.io
2. Log in with your username and password
3. Click on your user icon or name in the top-right corner
4. Select Settings (or navigate directly to auth.electricmonk.io/if/user/#/settings)

Step 2: Enroll a TOTP Device

1. In your user settings, find the MFA Devices section
2. Click Enroll → TOTP Authenticator
3. A QR code will be displayed on screen
4. Open your authenticator app on your phone and scan the QR code
   • In Google Authenticator: tap + → Scan a QR code
   • In Authy: tap Add Account → Scan QR Code
5. Your authenticator app will begin generating 6-digit codes that refresh every 30 seconds
6. Enter the current 6-digit code from your app into the verification field in Authentik
7. Click Save / Verify

Your TOTP device is now enrolled. From this point on, any application that uses Authentik for login will prompt you for your TOTP code after you enter your password.

Part 2 — Logging In With TOTP

Applications With Interactive Login (Most Services)

For most Electric Monk services — Cloud Storage, Matrix Chat, Vaultwarden, GitLab, PeerTube, and the Portal — you will be redirected to Authentik's login page. After entering your password, Authentik will automatically prompt you for your TOTP code on a second screen. Simply enter the current 6-digit code from your authenticator app.

Stalwart Mail (Password + TOTP Combined)

Stalwart's email login (IMAP/SMTP) does not show an interactive TOTP prompt. Instead, you combine your password and TOTP code into a single string using a semicolon (;) as the delimiter.

Format: yourpassword;123456

For example, if your password is hunter2 and your authenticator app shows 948372, you would enter:

hunter2;948372

This applies when logging into:

• The Stalwart admin panel at mail.electricmonk.io
• Any direct IMAP/SMTP client login (though app passwords are recommended instead — see below)

Tip: The TOTP code changes every 30 seconds. If your login fails, wait for a fresh code and try again.

Part 3 — Generating an App Password for Email Clients

Most email clients on iPhone, Android, and desktop computers do not support entering a TOTP code during login. For these clients, you need to generate an app password — a unique password that bypasses the TOTP requirement for that specific device.

Step 1: Log In to the Stalwart Admin Panel

1. Go to mail.electricmonk.io
2. Enter your username
3. Enter your password with your TOTP code appended, using a semicolon: yourpassword;123456
4. Click Log In

Step 2: Generate an App Password

1. Once logged in, navigate to Settings or your Account section
2. Find the App Passwords option
3. Click Create / Generate New App Password
4. Give it a descriptive name (e.g., "iPhone Mail", "Android Gmail", "Thunderbird")
5. A unique app password will be generated — copy it immediately

⚠️ Important: The app password is shown only once. If you lose it, you'll need to delete it and create a new one.

Step 3: Use the App Password in Your Email Client

Use this app password in place of your normal password when configuring your email client:

iPhone / iPad

1. Settings → Mail → Accounts → Add Account → Other
2. Select IMAP
3. Enter mail.electricmonk.io for both incoming and outgoing servers
4. Use your app password as the password
5. Ports: IMAP 993, SMTP 465, both with SSL/TLS

Android

1. Open your mail app (Gmail, K-9 Mail, FairEmail, etc.)
2. Add Account → Other / IMAP
3. Enter you@electricmonk.io and your app password
4. Incoming: mail.electricmonk.io, port 993, SSL/TLS
5. Outgoing: mail.electricmonk.io, port 465, SSL/TLS

Desktop (Thunderbird, macOS Mail, Outlook)

1. Add a new account with your email address and app password
2. If auto-detection doesn't work, manually enter:
   • IMAP: mail.electricmonk.io port 993 SSL/TLS
   • SMTP: mail.electricmonk.io port 465 SSL/TLS

Managing Your Devices and Passwords

Removing a TOTP Device

1. Go to auth.electricmonk.io → Settings → MFA Devices
2. Find the TOTP device you want to remove
3. Click Delete and confirm

Revoking an App Password

1. Log in to mail.electricmonk.io using password;totp
2. Go to App Passwords
3. Delete any app passwords you no longer need

Troubleshooting

"Invalid TOTP code"

• Make sure your phone's clock is accurate — TOTP depends on precise time sync
• Enable automatic date & time in your phone's settings
• Try waiting for the next code (they rotate every 30 seconds)

"Authentication failed" on email client

• Confirm you are using an app password, not your regular password + TOTP
• Verify the app password hasn't been revoked
• Double-check your username and server settings

Lost your authenticator app / phone

• Contact an administrator to reset your MFA devices in Authentik
• Once reset, log in and re-enroll a new TOTP device

App password not working

• Make sure you copied the full password with no extra spaces
• Try generating a new app password and replacing the old one