MFA Endpoints

API reference for all multi-factor authentication endpoints. These endpoints handle MFA verification during sign-in, TOTP and SMS enrollment, backup code generation, and MFA status checks.

All endpoints require Content-Type: application/json. Endpoints marked with Bearer JWT require a valid JWT in the Authorization header. See the MFA guide for flow diagrams and integration patterns.

Verify MFA

Complete MFA verification during sign-in. Exchanges a challenge token and MFA code for a JWT and refresh token.

Request body

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "rt_a1b2c3d4e5f6...",
  "user": {
    "id": "user_abc123",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "email_verified": true
  }
}

Error responses

Rate limits

• 5 attempts per 15 minutes per IP address

curl -X POST https://auth.example.com/api/proxy/mfa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "challenge": "ch_a1b2c3d4e5f6...",
    "code": "123456",
    "method": "totp"
  }'

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "rt_a1b2c3d4e5f6...",
  "user": {
    "id": "user_abc123",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "email_verified": true
  }
}

TOTP setup

Generate a TOTP secret and QR code for the user to scan with their authenticator app. Requires a valid JWT.

Authentication

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response 200

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code": "data:image/png;base64,iVBORw0KGgo...",
  "uri": "otpauth://totp/AuthGate:jane@example.com?secret=JBSWY3DPEHPK3PXP&issuer=AuthGate"
}

Error responses

Verify TOTP setup

Confirm TOTP setup by verifying a code from the user's authenticator app. This activates TOTP MFA for the user. Requires a valid JWT.

Authentication

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Request body

Response 200

{
  "success": true
}

Error responses

curl -X POST https://auth.example.com/api/proxy/mfa/totp/verify-setup \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

{
  "success": true
}

Remove TOTP

Remove TOTP MFA from the user's account. Requires a valid JWT and a current TOTP code for confirmation.

Authentication

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Request body

Response 200

{
  "success": true
}

Error responses

Enable SMS MFA

Enable SMS as an MFA method for the user. The user must have a verified phone number on their account. Requires a valid JWT.

Authentication

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response 200

{
  "success": true
}

Error responses

Remove SMS MFA

Remove SMS as an MFA method from the user's account. Requires a valid JWT.

Authentication

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response 200

{
  "success": true
}

Error responses

Send SMS code

Send an MFA verification code via SMS during the challenge flow. This endpoint does not require a JWT — it uses the challenge token to identify the user.

Request body

Response 200

{
  "success": true
}

Error responses

Generate backup codes

Generate a new set of 10 backup codes. Any existing backup codes are invalidated. Requires a valid JWT.

Authentication

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response 200

{
  "codes": [
    "a1b2c3d4",
    "e5f6g7h8",
    "i9j0k1l2",
    "m3n4o5p6",
    "q7r8s9t0",
    "u1v2w3x4",
    "y5z6a7b8",
    "c9d0e1f2",
    "g3h4i5j6",
    "k7l8m9n0"
  ]
}

Error responses

curl -X POST https://auth.example.com/api/proxy/mfa/backup-codes/generate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "codes": [
    "a1b2c3d4",
    "e5f6g7h8",
    "i9j0k1l2",
    "m3n4o5p6",
    "q7r8s9t0",
    "u1v2w3x4",
    "y5z6a7b8",
    "c9d0e1f2",
    "g3h4i5j6",
    "k7l8m9n0"
  ]
}

MFA status

Check the current MFA enrollment status for the authenticated user. Requires a valid JWT.

Authentication

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response 200

{
  "enrolled": true,
  "methods": ["totp", "sms", "backup_codes"],
  "required": true
}

Error responses

curl https://auth.example.com/api/proxy/mfa/status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "enrolled": true,
  "methods": ["totp", "backup_codes"],
  "required": false
}