Setup MFA

---

Use the Setup MFA screen to add time-based one-time password (TOTP) authentication to a doctor account. Requires an authenticated user session.

This screen runs inside an authenticated session. No separate API calls are required to configure MFA. MFA state is stored in the authenticated user session and persisted on the backend.
Integrators must embed this screen in a secure, logged-in flow. Upon completion, the screen redirects to the Edit Account screen.

This screen includes:

• A QR code and copyable secret key for registering an authenticator app.
• A numeric input field for entering a 6-digit TOTP code.
• Compatibility with apps such as Google Authenticator, Microsoft Authenticator, and Authy.
• Inline validation for expired, missing, or incorrect codes.
• A success banner when MFA activates.
• 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. From the navigation menu, open Account > Edit Account > Security: 2-Step Verification.

2. Open an authenticator app and scan the QR code, or manually enter the key.
   → The app registers the key and begins generating TOTP codes.

   

3. Enter the 6-digit verification code into the input field.

   

4. Select Verify. → MFA activates, and the app redirects the user to the Edit Account screen.

---

Validations

• Accepts only a valid 6-digit TOTP code.
• Rejects expired, missing, or incorrect codes.
• Disables the Verify button until the code format is valid.
• Blocks setup if the authenticator secret fails to register.
• Requires MFA verification on the next login after setup.

Actions

• Persists the MFA activation state in the backend for the authenticated account.
• Redirects to the Edit Account screen.
• Adds the Unlink Authenticator App option.
  → See Unlink Authenticator App.
• Prompts for a verification code at the next login.
  

---

SDK and API References

SDK Reference

GET 

/account/mfa

Returns the MFA status for the current authenticated account. If no MFA configuration exists, the screen prompts the user to complete setup.

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

API Reference

API details coming soon.