Multi-Factor Authentication
Context and Why This Exists
Multi-factor authentication adds a second security check when you sign in.
This exists to protect access to sensitive information and higher-risk features, especially connected services such as Xero Practice Manager (XPM). A password alone is not enough protection when users can access client data, integration settings, or other sensitive records.
In StructureGram:
- MFA is optional for general users who want extra account protection.
- MFA becomes required when you use Xero integration features.
- Once MFA is enabled, you are asked to verify on login until your session is upgraded.
What the Feature Does
StructureGram uses an authenticator app-based MFA flow.
When MFA is enabled, you sign in with:
- your normal email and password, and then
- a 6-digit code from your authenticator app, or a recovery code if needed.
After setup, StructureGram also gives you recovery codes. These are single-use backup codes for cases where you lose access to your authenticator.
Where to Manage It
You manage MFA from:
- Account -> Security for setup and day-to-day management
- /verify-mfa during sign-in or when StructureGram needs proof of MFA for a protected action
How to Set Up MFA
- Open Account -> Security.
- Click Enable 2FA.
- Optionally give the authenticator a name.
- Scan the QR code in your authenticator app, or enter the manual key.
- Enter the 6-digit code from the app.
- If this is your first authenticator, StructureGram shows a set of recovery codes. Save them, then tick I have saved these recovery codes in a secure place.
If you already have unused recovery codes, setup keeps them and shows no new ones. The message reads "Your saved recovery codes still work ({count} left). Keep them somewhere safe: they work whichever authenticator you use." If you don't have them, click Don't have them? Get a new set. Your old codes then stop working.
After setup, the security page shows your MFA status and any enrolled authenticators.
How Verification Works at Sign-In
If your account requires MFA, StructureGram redirects you to the verification page after password sign-in.
You can then:
- enter a 6-digit authenticator code, or
- switch to a recovery code.
After successful verification, StructureGram sends you back to the page you were trying to access.
How Xero XPM Changes the Rules
Xero integration adds a stricter security requirement.
If you connect to Xero XPM:
- MFA is required,
- you cannot turn it off while the Xero connection remains active,
- and you cannot remove your last authenticator while Xero still requires MFA.
This protects access to integration actions and XPM-linked data.
Adding Another Authenticator
You can add more than one authenticator.
This is useful if you want:
- one authenticator on your phone,
- and a second fallback authenticator in another trusted app or device.
If you already have MFA enabled but your current session is not fully MFA-verified, StructureGram first asks you to verify with your existing authenticator before adding another one.
Adding another authenticator keeps your existing recovery codes. Each code works with any of your authenticators.
Recovery Codes
Recovery codes are backup access codes created after MFA setup.
Important points:
- Each recovery code can be used once.
- They should be stored securely.
- Each code works with any of your authenticators.
- The security page shows how many unused recovery codes remain.
Signing In with a Recovery Code
On the verification page, click Use a recovery code. The page explains: "Enter one of your recovery codes. Your current authenticator will be removed, and you will set up a new one."
When the code is accepted, StructureGram removes your authenticators and asks you to set up a new one. Verifying the new authenticator finishes your sign-in. Your remaining recovery codes keep working.
Getting New Recovery Codes
Get a new set if you never saved your codes, lost them, or think someone has seen them.
- Open Account -> Security.
- Click Get new recovery codes.
- Read the warning: "Your current recovery codes will stop working, including any you have saved."
- Click Get new codes, or Cancel to keep your current codes.
- Save the new codes, tick I have saved these recovery codes in a secure place., then click Done.
You can't close the dialog until you tick that the new codes are saved.
Edge Cases and Expected Behavior
MFA can be enabled even if you do not use Xero
You do not need a Xero connection to use MFA. You can enable it voluntarily for extra protection.
Xero-connected users cannot freely disable MFA
If Xero requires MFA for your account, the Security page blocks:
- disabling all MFA, and
- removing the last remaining authenticator.
You may be asked to verify before adding a second authenticator
If you already use MFA but your session is not at the higher assurance level, StructureGram asks you to verify with an existing code first.
Recovery code access is built into the verification flow
On the MFA verification page, you can switch between authenticator-code entry and recovery-code entry with Use a recovery code and Use authenticator app instead. Using a recovery code removes your authenticators, so you then set up a new one.
Troubleshooting (Q&A)
I cannot connect to Xero because StructureGram says MFA is required
Most likely cause:
- Your account does not yet have a verified authenticator.
Fix:
- Go to Account -> Security.
- Click Enable 2FA.
- Complete setup.
- Return to Account -> Integrations and try the Xero connection again.
I enabled MFA, but I still got sent to the verification page
Cause:
- MFA setup and MFA sign-in verification are different steps.
Fix:
- Enter the current code from your authenticator app.
- After successful verification, continue to the original page.
I cannot disable 2FA
Most likely cause:
- Your Xero connection still requires MFA.
Fix:
- Open Account -> Integrations.
- Disconnect Xero if you no longer need the integration.
- Return to Account -> Security.
- Disable 2FA again.
I cannot remove my last authenticator
Most likely cause:
- Xero MFA enforcement is active for your account.
Fix:
- Either keep at least one authenticator enrolled, or
- disconnect Xero first, then remove the authenticator.
My authenticator code is not accepted
Most likely causes:
- The device clock is out of sync.
- You entered an expired 6-digit code.
- You used the wrong authenticator.
Fix:
- Wait for a fresh code.
- Confirm you are using the correct authenticator entry.
- Check the device time on your phone or computer.
- If needed, use a recovery code instead.
I lost access to my authenticator app
Fix:
- Use a recovery code on the verification page if you still have one.
- Set up a new authenticator when StructureGram asks. This finishes your sign-in.
- If you have lost both the authenticator and recovery codes, use the support option on Account -> Security.
Best Practice
Use at least one primary authenticator and keep recovery codes stored separately in a secure place.
If you depend on Xero XPM, it is better to enrol a second authenticator before you need it rather than waiting for a lost-device event.