Enable MFA

---

Use the Authentication Setup screen to enable time-based one-time password (TOTP) authentication for a user account.
The Air Doctor app stores MFA state in the user session and syncs this state with the backend.
Integrators place this screen inside a secure, authenticated flow. After setup, the app redirects to the Edit Account screen.

This screen includes:

• A QR code and copyable secret key for an authenticator (such as Google Authenticator, Microsoft Authenticator, and Authy.
• A numeric input field for a 6-digit TOTP code.
• Inline validation for expired, missing, or incorrect codes.
• A success banner after MFA activation.
• Automatic redirection to the Edit Account screen.

MFA Interaction Flow

+----------------+       +--------------------+       +---------------------+
|     User       |       | Authenticator App  |       | Air Doctor Backend  |
+----------------+       +--------------------+       +---------------------+
        |                         |                             |
        | Open Setup MFA Screen   |                             |
        |------------------------>|                             |
        |                         |                             |
        | Scan QR / Enter Key     |                             |
        |------------------------>|                             |
        |                         | Start TOTP generation       |
        |                         |---------------------------->|
        |                         |                             |
        | Enter Code              |                             |
        |------------------------>|                             |
        |                         | Validate Code               |
        |                         |---------------------------->|
        |                         |                             |
        | Success Banner & Redirect                             |

---

Workflow

1. Open the Account screen.
2. Select Edit account.
3. Select Security: 2-Step Verification.
4. Open an authenticator app. Scan the QR code or enter the secret key.
   The authenticator app generates time-based one-time passwords (TOTP).
5. Enter the 6-digit verification code from the authenticator app.
   
6. Select Verify to enable MFA.
   MFA activates, and the app redirects to the Edit Account screen.

---

Validations

Scenario	App Behavior	SDK Output
Code has a format other than six digits.	Disables Verify and highlights the input field.	Returns a validation error for invalid code format.
Code is missing.	Disables Verify and prompts for input.	Returns error metadata for a missing code.
Code is expired or incorrect.	Displays an inline error and keeps the user on the setup screen.	Returns an error that identifies an invalid or expired TOTP code.
Secret cannot register for the account.	Displays an error banner and prevents activation.	Returns an error that identifies a registration failure.

MFA also requires a valid verification code on the next login after activation.

Actions

Scenario	App Behavior	SDK Output
User enters a valid code and selects Verify.	Persists MFA activation state in the backend for the authenticated account.	Returns an updated profile or session state with MFA enabled.
MFA activates.	Redirects to the Edit Account screen.	Returns success status metadata.
MFA is active for the account.	Displays the Unlink Authenticator App option.	Exposes MFA state so the app can open Unlink Authenticator App.
User completes setup.	Prompts for a verification code on the next login for this account.	Returns an MFA-required state when the account logs in again.

---

Endpoint Resources

Authentication Enabled

PUT 

v3/account/mfa/enable

This endpoint returns MFA setup data and confirms that the account is ready for activation.
The response includes the secret key, QR code data, and configuration for the Authentication Setup screen.

UI Element Types

Level	Reference	Type	Value
1	verification	Regular	Additional verification is available
1	scan-qr	Regular	First, scan this QR code with your authenticator app.
1	install-app	Regular	You'll need to install an authenticator app, such as Authy or Google Authenticator.
1	qr-code	Illustration	[QR code]
1	enter-key	Regular	or enter key
1	secret	Link	[explicit code]
1	enter-code	Regular	Next, enter the 6-digit code generated by your authenticator app here.
1	mfa	Integer	Verification code
1	verify	Button	Verify
1	learn-more	Link	Learn more

Verify Authentication Code

POST 

v3/account/mfa/enable

This endpoint validates the TOTP code against the stored secret and enables MFA.