balena 2FA: how to set up an authenticator app for balenaCloud

A balenaCloud account controls fleets of connected devices: the code they run, SSH access to them, and the API keys that can change all of it. That makes it worth more than a password. balena's two-factor authentication (2FA) is optional and uses one method, a time-based code from an authenticator app (TOTP). There's no text-message option in the docs (balena, balena). This guide uses Authenticator App - Novaz on iPhone, but any authenticator app works the same way.

How we checked this guide: the balena steps come from balena's own documentation, linked below, which we read on October 21, 2026. For lockouts, we also read replies from balena's team on its official forum. We haven't tested any of this on a balenaCloud account, 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

balena's account documentation describes these steps (balena):

1. Sign in to the balenaCloud dashboard. Click your profile in the top right and open the Preferences page.
2. Open the Two-factor Authentication tab and click Enable two-factor authentication.
3. balena shows a QR code and a Pairing code field. In Novaz, tap +, then Scan QR code, and point the camera at the code on your monitor. If the dashboard is open on the same iPhone, take a screenshot, tap +, then Choose a photo. See scanning a QR code on the same iPhone.
4. Type the 6-digit code from Novaz into Pairing code.
5. balena then shows your recovery codes. Download them and keep them somewhere safe, then click OK.

The docs point out that 2FA only switches on once pairing succeeds, so you can't lock yourself out by leaving halfway.

balena's docs don't mention a text key you could type instead of scanning, and they don't say how often the codes change. Scan the QR code: it carries the code settings to your app. If you do find a key and type it with Enter key manually, Novaz assumes 6 digits every 30 seconds. See What is a 2FA setup key?

balena's list of verified apps names Google Authenticator, Authy and 1Password. Novaz isn't on it, but it makes the same standard TOTP codes.

If you sign in with SAML

If you use your company's single sign-on and get an error every time you try to enable 2FA, balena's suggestion is to log out, sign back in, and try again right away (balena).

When balena asks for a code

After setup, balena asks for the code from your app at the next sign-in, once you've entered your username and password (balena). The docs don't mention remembered or trusted devices.

On the command line, balena login takes your email, password and a 2FA code, or lets you authorize the CLI from the dashboard, or accepts a session token or API key (balena). API keys never expire unless revoked and carry your full permissions (balena), so guard them like your recovery codes.

Keep your recovery codes

Recovery codes are the only backup balena documents. They're your way back in if the phone is gone and you have no Novaz backup, or only one made before you added balena. Store them in a password manager or on paper, away from the phone. More in 2FA backup codes.

If balena rejects your code

balena's docs say a code stops working once the countdown in your app runs out, so enter it while it's still showing. If fresh codes keep failing, check your iPhone's clock: Settings > General > Date & Time > Set Automatically. Novaz warns you when the clock is 15 seconds or more off. Other causes are in Authenticator code not working?

Changing phones

balena's docs don't describe moving 2FA to a new phone. The steps they do give are turning it off and on again. While you still have the old phone, disable 2FA, then enable it again and scan the new QR code with the new iPhone. If you turned on Novaz's iCloud backup or saved a backup file, restoring it on the new iPhone is the simpler way: the codes keep working. See How to transfer your authenticator app to a new iPhone.

If you lose your authenticator

Sign in with one of your recovery codes. Without them, balena's docs offer no self-service route. The documented place for help is the product support section of balena's forums (balena).

In a 2023 forum thread, replies from balena's team, including a listed forum moderator, described the process. Recovery codes are the fastest way to prove the account is yours. Failing that, balena checks that you hold the private half of an SSH key you added to your balenaCloud account. You sign a string they give you and send the result to a balena team member privately, never in a public post. Once the signature checks out, balena removes 2FA so you can sign in with your password alone (balena forums). This comes from forum replies, not the docs, and balena doesn't say how long it takes. If you use SSH with your devices, keep that key. More in Lost the phone with your authenticator app?

Turning 2FA off

Go back to the Two-factor Authentication tab in your preferences and click Disable two-factor authentication. balena asks for your account password first (balena). If you signed up with GitHub or Google and never set a password, you can add one under the Account details tab of the same page.

Official balena help

• Account management
• Security
• Enterprise Single Sign-On (SSO): Introduction
• Balena CLI reference (latest)
• Getting Help
• Disable 2FA Reset without recovery codes (balenaForums thread with replies from balena's team)