Multi-Factor Authentication

TOTP-based MFA setup and verification endpoints

Updated Dec 29, 2025 Edit this page

Multi-Factor Authentication

TOTP-based multi-factor authentication endpoints for enhanced account security.

Overview

AuthOS supports TOTP (Time-based One-Time Password) second-factor authentication compatible with apps like Google Authenticator, Authy, and 1Password.

Features:

  • 6-digit TOTP codes (RFC 6238)
  • 10 backup codes for recovery
  • QR code for easy setup
  • Backup codes are single-use

Endpoints

Method Path Description
POST /api/auth/mfa/verify Verify MFA during login

See User Management API for MFA setup endpoints.

POST /api/auth/mfa/verify

Verify MFA code during login and complete authentication.

Synopsis

Property Value
Authentication Pre-auth token required
Rate Limit 5/minute

Request Body

Field Type Required Description
preauth_token string Yes Pre-auth JWT from login
code string Yes 6-digit TOTP code or backup code
device_code_id string No Device code ID for device flow

Example Request

curl -X POST https://sso.example.com/api/auth/mfa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "preauth_token": "preauth_token_eyJhbGciOiJSUzI1NiIs...",
    "code": "123456"
  }'

Response (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "550e8400-e29b-41d4-a716-446655440000",
  "expires_in": 86400
}

Errors

Status Code Condition
400 INVALID_MFA_CODE Incorrect TOTP or backup code
400 BAD_REQUEST Invalid pre-auth token
429 RATE_LIMIT_EXCEEDED Too many failed attempts

MFA Login Flow

sequenceDiagram
    participant User
    participant Client
    participant AuthOS
    participant Authenticator

    User->>Client: Enter email + password
    Client->>AuthOS: POST /api/auth/login
    AuthOS-->>Client: {mfa_required: true, preauth_token}
    Client->>User: Show MFA prompt
    User->>Authenticator: Get TOTP code
    Authenticator-->>User: 123456
    User->>Client: Enter code
    Client->>AuthOS: POST /api/auth/mfa/verify
    AuthOS-->>Client: {access_token, refresh_token}
    Client->>User: Logged in

Backup Codes

Backup codes can be used instead of TOTP codes:

  • 10 codes generated during MFA setup
  • Each code is single-use
  • Format: 8-character alphanumeric
  • Can be regenerated (invalidates old codes)

Example backup code: ABCD1234

Code Validation

TOTP Codes

  • 6 digits
  • Valid for 30-second window
  • ±1 window tolerance for clock skew

Backup Codes

  • 8 characters
  • Case-insensitive
  • Single-use only
  • Deleted after successful use

Security Considerations

  1. Rate Limiting - 5 attempts per minute prevents brute force
  2. Pre-auth Token Expiry - 10-minute window for MFA completion
  3. Backup Code Hashing - Codes hashed with Argon2id
  4. Session Revocation - Disabling MFA revokes all sessions