Home Assistant 2FA: how to set up an authenticator app

Home Assistant has two accounts, and only one can take a new authenticator app today. This guide covers the first: your user account on your own Home Assistant system, which you sign in to from a browser or the companion app. The second, your Home Assistant Cloud account with Nabu Casa for remote access, doesn't let you turn on two-factor authentication at the moment (see the last section).

Two-factor authentication (2FA) is optional on that login, but Home Assistant's security advice is to turn it on (Home Assistant). It can also send codes through a notification action. This guide uses Authenticator App - Novaz on iPhone. Any authenticator app works the same way.

How we checked this guide: the Home Assistant steps come from Home Assistant's own documentation and Nabu Casa's support center, linked below, which we read on October 19, 2026. We haven't tested them on a Home Assistant system, so a label may differ slightly. The Novaz steps are checked against the app, version 1.0.5.

Turn on 2FA with an authenticator app

Each person turns it on in their own profile, since the setting only covers your own account (Home Assistant). The documented steps (Home Assistant, Home Assistant):

1. Select your name at the very bottom of the sidebar to open your User profile, then open Security.
2. In the Multi-factor authentication modules section, under Authenticator app, select Enable. Home Assistant creates a new secret key and shows it as a QR code, with the key as text below it.
3. In Novaz, tap +, then Scan QR code. If Home Assistant is open on the same iPhone, take a screenshot and use Choose a photo instead. See scanning a QR code on the same iPhone.
4. Or tap +, then Enter key manually, and type the text below the QR code as the Setup key. Its six-digit codes, which change about every 30 seconds, match what Novaz uses for a typed key. See What is a 2FA setup key?
5. Where Home Assistant asks for a Code, under the QR code, enter the current code from Novaz.

The docs warn to treat the secret key like a password. You normally don't need to edit files: the Authenticator app module loads by itself when configuration.yaml has no auth_mfa_modules section. If yours has one, add - type: totp to it and restart Home Assistant first (Home Assistant).

When Home Assistant asks for a code

Home Assistant asks for the latest code when you sign in (Home Assistant). Each sign-in creates a refresh token that keeps that device signed in, and tokens unused for 90 days are removed (Home Assistant). So expect the prompt on a new browser or phone, after signing out, and on a device you haven't used in months. With more than one method on, you pick one at sign-in.

Logins through the trusted networks provider, which lets listed networks in without a password, skip the code entirely (Home Assistant).

If Home Assistant rejects your code

Two clocks matter here. If verification keeps failing, the docs say to check the clock on your Home Assistant system first (Home Assistant). Then, on the iPhone, open Settings > General > Date & Time and turn on Set Automatically. Novaz also warns you when the iPhone's clock is 15 seconds or more off. More causes are in Authenticator code not working?

No backup codes, so plan a way back in

Home Assistant's documentation doesn't mention backup codes for the authenticator app, and its I'm locked out! page covers forgotten usernames and passwords only (Home Assistant). Novaz's keys stay on your iPhone unless you turn on iCloud backup or export a backup file, and a backup can be out of date. So keep another way in:

• stay signed in on a computer or tablet you use regularly, so you can reach Security without a code;
• add notification codes, set up in configuration.yaml, as a second method; Home Assistant can't tell whether they arrive (Home Assistant);
• or save the setup key in a password manager.

If you lose your authenticator or change phones

Home Assistant's docs don't describe moving the authenticator. You turn it on and off on the Security page, and Enable makes a new key each time (Home Assistant). So, from any device that's still signed in, turn the authenticator app off, enable it again, and scan the new QR code with your new iPhone. With a Novaz iCloud backup or backup file, you can restore your accounts on the new iPhone instead and keep the same key. Without one, do this before giving up the old one. See How to transfer your authenticator app to a new iPhone.

If the phone is lost and no device is signed in, notification codes can get you in, if you turned them on and they reach a device you still have. Beyond that, the docs don't describe a fix, and they don't say an administrator or the owner can turn off another user's 2FA. More in Lost the phone with your authenticator app?

Home Assistant Cloud (Nabu Casa)

Nabu Casa says turning on two-factor authentication for Home Assistant Cloud is "currently not available" (Nabu Casa). If you set it up earlier, it keeps working, but:

• Only Customer Support can turn it off, from a ticket, and you can't turn it back on for now (Nabu Casa).
• A lost authenticator means a support ticket too (Nabu Casa). Nabu Casa doesn't describe showing the key again, so unless you can restore a Novaz backup on a new iPhone, plan on a ticket for that as well.
• Home Assistant older than 2025.1.0 can't sign in to Cloud with it and shows Unexpected error - software token MFA. Updating fixes it (Nabu Casa).

Remote access puts your login page on the internet, so Nabu Casa advises 2FA in Home Assistant for every user account (Nabu Casa).

Official Home Assistant help

• Multi-factor authentication
• Authentication
• People and user configuration
• Authentication providers
• I'm locked out!
• Securing your Home Assistant
• Enabling multi-factor authentication (MFA) for Home Assistant Cloud
• Disabling MFA (multi-factor authentication) for Home Assistant Cloud
• I lost the device that I use to generate the MFA token
• Can't log into Cloud. "Authentication failed", or "Unexpected error - software token MFA"
• Remote access - Security aspects