Mattermost 2FA: how to set up an authenticator app
By the Novaz team · Updated October 29, 2026
Novaz steps checked against version 1.0.5
On this page
Your Mattermost account lives on the server or workspace your organization runs, and that server's system admin decides whether you can use two-factor authentication, whether you must, and who fixes it when it breaks. Mattermost calls it multi-factor authentication (MFA), and it covers every team on the server (Mattermost).
The one method is a code from an authenticator app; the docs describe no text-message option. It's optional unless your admin enforces it. This guide uses Authenticator App - Novaz on iPhone, but any authenticator app works the same way.
How we checked this guide: the Mattermost steps come from Mattermost's own documentation, linked below, which we read on October 20, 2026. We haven't tested them on a Mattermost account, so a label may differ slightly. The Novaz steps are checked against the app, version 1.0.5.
First, check that your server allows it
You'll only find the setting when all of these are true:
- Your admin has turned MFA on. It's off by default. An admin turns it on in the System Console under Authentication > MFA by setting Enable Multi-factor Authentication to true (Mattermost). If your security settings have no Multi-factor Authentication row, ask your admin.
- You sign in with an email address or AD/LDAP. If you sign in through single sign-on, such as SAML, Google or Entra ID, the second factor belongs to that provider, outside Mattermost (Mattermost).
- You're a full member, or MFA is enforced. Guest accounts can use MFA only when the admin enforces it (Mattermost).
If your admin enforces MFA (Enforce Multi-factor Authentication, in the same place), Mattermost takes you to a setup page when you sign in, and you can't use it until you finish. New users do this while signing up (Mattermost).
Turn on 2FA with an authenticator app
Mattermost's user docs give these steps (Mattermost):
- Open Mattermost in a web browser or the desktop app. The docs only describe these two.
- Select your profile picture, then Profile > Security.
- Under Multi-factor Authentication, select Edit.
- Select Add MFA to Account. Mattermost gives you a QR code and a text key it calls the Secret.
- In Novaz, tap +, then Scan QR code, and point the camera at the code. If Mattermost is open on the same iPhone, take a screenshot and use Choose a photo. See scanning a QR code on the same iPhone.
- If you can't scan it, tap +, then Enter key manually, and type the Secret as the Setup key. See What is a 2FA setup key?
- Back in Mattermost, type the code from Novaz into MFA Code and select Save.
The docs don't say how many digits the codes have or how often they change, so scan the QR code if you can: it carries those settings to Novaz, while a typed key always gets 6 digits every 30 seconds.
No backup codes
Mattermost's docs mention no backup or recovery codes and no second way to sign in. Novaz can restore its keys on a new iPhone from iCloud backup or a backup file, but without one they exist only on your phone, and if that phone is gone, your system admin is the only documented way back in. Before you turn MFA on, know how to reach your admin outside Mattermost.
When Mattermost asks for a code
You type a code after your username and password when you sign in (Mattermost). Mattermost's user docs say a sign-in on a browser or device can last up to 30 days, so you won't see the prompt every day (Mattermost).
Two other prompts can look like a code request:
- The Authentication secret under Advanced Options in the mobile app is a server-wide secret from your admin, not a Novaz code (Mattermost).
- On a server running in hardened mode, the code screen can appear even if you never set up MFA. Mattermost's admin docs say any value gets you past it then, unless MFA is enforced (Mattermost).
If Mattermost rejects your code
Check your iPhone's clock first: Settings > General > Date & Time > Set Automatically. Novaz warns you when it's 15 seconds or more off. The server's clock matters too: Mattermost says a wrong server time can stop people signing in (Mattermost). If your phone is right and coworkers have the same trouble, tell your admin. Other causes are in Authenticator code not working?
Changing phones
Mattermost doesn't document a phone move, but you can remove MFA yourself under Profile > Security > Multi-factor Authentication while it isn't enforced (Mattermost). With the old phone still working, remove it there and add it again on the new one. The docs don't name the remove button.
If MFA is enforced, ask your admin to reset it; you'll set it up again at your next sign-in (Mattermost). With a Novaz iCloud backup or backup file, you can restore the account on the new iPhone instead. See How to transfer your authenticator app to a new iPhone.
If you lose your authenticator
Contact your system admin. Mattermost gives users no self-service recovery, but an admin can turn off MFA on your account with the mmctl user resetmfa command or through Mattermost's API (Mattermost, Mattermost). The docs don't say what proof an admin should ask for or how long a reset takes. More in Lost the phone with your authenticator app?
Turning 2FA off
If MFA isn't enforced, remove it where you added it. If the admin turns MFA off for the whole server, you can no longer add or remove it on your account (Mattermost).
Mattermost can email you when MFA is turned on or off for your account (Mattermost). If one arrives and you didn't make the change, tell your admin.
