Two-Factor Authentication (2FA)

Add an extra layer of security with SMS-based verification codes

Overview

Two-factor authentication in Instafill.ai is implemented in SecurityController.cs and uses the Twilio 7.11.1 SDK to deliver 6-digit SMS codes. The critical property of the implementation is that the final JWT (issued by JwtKeyManager.cs) is not produced until the second factor is verified — the first-factor check and the SMS delivery happen as separate steps, with the session only fully established after the SMS code is confirmed.

The JWT issued after 2FA passes is identical in format to tokens issued through email/password or OAuth sign-in, so the rest of the system — including the JWT middleware in both the .NET and Python service layers — treats the session the same way regardless of whether 2FA was required.

In addition to SMS, TOTP-based authenticator apps (time-based one-time password) are also supported for users who prefer app-based verification.

Real-World Example: A teleradiology practice automated hospital credentialing by 92%, processing 50+ credentialing packages monthly. They enforced mandatory 2FA across all staff to meet HIPAA requirements and protect physician credentials.

Organizations can enforce 2FA for all workspace members at the Enterprise tier. When enforcement is active, users without a verified second factor cannot complete login — SecurityController.cs blocks JWT issuance until the second factor is enrolled and confirmed.

Key Capabilities

• SMS via Twilio 7.11.1 SDK: 6-digit codes delivered via Twilio's SMS infrastructure; Twilio 7.11.1 is the SDK version in use
• TOTP Authenticator App Support: Time-based one-time passwords (RFC 6238) work with apps such as Google Authenticator and Authy as an alternative to SMS
• JWT Gated on Second Factor: SecurityController.cs withholds JWT issuance until the SMS code or TOTP code is confirmed — partial authentication cannot be used to access the API
• Organization-Wide Enforcement (Enterprise): Org-level admins can require 2FA for all workspace members; users without enrollment are blocked from completing login after the grace period
• Grace Period for Enforcement: When an organization enables mandatory 2FA, users receive a configurable grace period (default 7 days) before enforcement blocks login
• Trusted Devices: Devices can be marked as trusted during login; trusted devices skip the 2FA step for 30 days
• Backup Codes: One-time-use backup codes generated at enrollment for phone-loss recovery
• Service Account Exemption: Accounts used exclusively with API keys can be exempted — API keys are validated by JWT middleware without an SMS step

How It Works

1. Enable 2FA (User-Level):

   • Navigate to Account Settings → Security
   • Click "Enable Two-Factor Authentication"
   • Choose SMS (enter mobile phone number and verify) or authenticator app (scan QR code)
   • Download and store backup codes

2. Organization Enforcement (Enterprise):

   • Organization admin enables "Require 2FA" in org security settings
   • SecurityController.cs begins blocking JWT issuance for non-enrolled users after the grace period expires
   • Users receive email notification with the grace period deadline and setup instructions
   • After the grace period, unenrolled users are prompted to set up 2FA at next login before access is granted

3. Login with 2FA:

   • User completes first factor (email/password or OAuth)
   • SecurityController.cs triggers Twilio 7.11.1 SMS to the registered phone number, or prompts for TOTP code if authenticator app is configured
   • User enters the 6-digit code within the expiration window (5 minutes for SMS)
   • Code verified — JwtKeyManager.cs issues the session JWT
   • Optionally mark the device as trusted (skips 2FA for 30 days on that device)

4. Backup Code Usage:

   • If the phone is unavailable, click "Use backup code" on the 2FA prompt
   • Enter one of the pre-generated codes; SecurityController.cs accepts it in place of the SMS/TOTP code
   • Each backup code is single-use; generate a fresh set after using one

Use Cases

Two-factor authentication is used by compliance-driven teams to meet regulatory access control requirements. Healthcare practices filling CMS-1500 claims or I-485 immigration forms enable 2FA to satisfy HIPAA's technical safeguard mandates for access to electronic PHI. Law firms handling confidential client matters use it to ensure that a stolen laptop with a saved browser session cannot grant access to case documents without the user's phone. Enterprises enforce 2FA organization-wide so that the access control policy applies to every workspace member automatically, without relying on individual users to opt in.

Benefits

• Second Factor Before JWT: The session JWT is only issued after both factors are verified — there is no partially-authenticated state that could be exploited
• No App Required for SMS: SMS 2FA works on any mobile phone; TOTP support available for users who prefer app-based verification
• Compliance Support: Meeting HIPAA technical safeguard requirements for MFA, SOC 2 access control criteria, and similar frameworks is straightforward when enforcement is organization-wide
• Trusted Device Convenience: Regular users on known devices are prompted only once every 30 days rather than at every login
• API Automation Unaffected: API key-based integrations bypass interactive 2FA — the workflow automation is not interrupted while interactive logins remain protected

Security & Privacy

Data is scoped to workspaceId and protected via the shared JWT authentication middleware running in both the .NET and Python service layers.

Code Security:

• SMS codes: 6 digits, 5-minute expiration, rate-limited to prevent brute force
• TOTP codes: RFC 6238 compliant, 30-second window, standard 6-digit format
• Codes are single-use; a successfully verified code cannot be replayed

JWT Gating:

• SecurityController.cs does not call JwtKeyManager.cs until the second factor is confirmed
• An intercepted first-factor session cannot be used to access the API without completing the second factor

Phone Number Privacy:

• Phone numbers are encrypted at rest
• Displayed masked in the UI (e.g., --1234)
• Not shared with third parties beyond Twilio for SMS delivery

SMS Delivery:

• Sent via Twilio 7.11.1 SDK over Twilio's secure infrastructure
• Delivery failures trigger retry logic before surfacing an error to the user

Backup Codes:

• Generated as cryptographically random values
• Stored as hashes — plain-text codes are never persisted after generation
• Each code is single-use; a used code cannot grant access again

Common Questions