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
-
From the navigation menu, open Account > Edit Account > Security: 2-Step Verification.
-
Open an authenticator app and scan the QR code or enter the secret key. The authenticator app uses the key to create TOTP codes.
-
Enter the 6-digit Verification code from the authenticator app.
-
Select Verify. 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
/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
/account/mfa/enable
This endpoint validates the TOTP code against the stored secret and enables MFA.