Verify MFA

Verify MFA code using temporary token and complete login process.

Endpoint

POST /api/v1/auth/mfa/verify

Headers

Header	Required	Description
Content-Type	Yes	application/json
x-device-fingerprint	No	JSON string with device fingerprinting data

Request Body

{
  "temporary_token": "temp_token_from_mfa_generate",
  "code": "123456",
  "backup_code": null
}

Parameters

Field	Type	Required	Description
temporary_token	string	Yes	Temporary token from MFA OTP generate
code	string	No	6-digit OTP or TOTP code
backup_code	string	No	Backup code (alternative to code)

Validations

• Temporary token validation
• Code format validation (6 digits)
• OTP/TOTP code verification
• Backup code verification (if used)
• Attempt limit check

Response

Success (200)

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer",
    "expires_in": 3600,
    "user_id": 123,
    "email": "user@example.com",
    "display_name": "John Doe",
    "is_verified": true,
    "trusted_device": {
      "id": 789,
      "device_name": "Chrome on Windows",
      "activation_token": "activation_token_here",
      "expires_at": "2024-01-01T12:05:00Z",
      "is_active": false
    }
  },
  "message": "MFA verification successful"
}

Error Codes

Status	Code	Description
400	INVALID_MFA_CODE	Invalid MFA code
401	INVALID_TOKEN	Invalid temporary token
401	USER_NOT_FOUND	User not found or disabled
422	VALIDATION_ERROR	Request validation failed

Data Flow

1. Token Validation

   • Validate temporary token from Redis
   • Extract user ID, session ID, and challenge data

2. Code Verification

   • For email_otp: Verify OTP code from Redis
   • For totp: Verify TOTP code using MFA service
   • For backup_code: Verify backup code hash

3. MFA Method Update

   • Update MfaMethod last_used timestamp
   • Mark backup code as used if applicable

4. Session Completion

   • Complete session creation
   • Link session to user

5. Token Generation

   • Generate OAuth2 access token
   • Generate refresh token

6. Device Trust Setup

   • Generate device fingerprint
   • Create trusted device entry (inactive)
   • Generate activation token (5 minute expiry)

7. Token Cleanup

   • Invalidate temporary token
   • Clean up MFA challenge

8. Audit Logging

   • Log successful MFA verification
   • Record method used

Features

• Verifies MFA code with temporary token
• Completes login process
• Returns access and refresh tokens
• Creates trusted device entry for "remember device" functionality
• Invalidates temporary token after use
• Supports OTP, TOTP, and backup codes

Example

curl -X POST https://api.rivergen.com/api/v1/auth/mfa/verify \
  -H "Content-Type: application/json" \
  -H "x-device-fingerprint: {\"screen\":\"1920x1080\"}" \
  -d '{
    "temporary_token": "temp_token_from_mfa_generate",
    "code": "123456"
  }'

Related Endpoints

• Login - Initial login
• Generate MFA OTP - Generate OTP code
• Activate Device - Activate trusted device