Multi-Factor Authentication

TOTP-based MFA with recovery codes

Overview

Scalix Auth supports TOTP (Time-based One-Time Password) for multi-factor authentication. Users can enroll with any authenticator app (Google Authenticator, Authy, 1Password).

Enroll MFA

bash

curl -X POST https://api.scalix.world/v1/auth/mfa/enroll \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"friendly_name": "My Phone"}'

Response:

json

{
  "factor_id": "fac_abc123",
  "factor_type": "totp",
  "friendly_name": "My Phone",
  "totp": {
    "secret": "JBSWY3DPEHPK3PXP",
    "uri": "otpauth://totp/Scalix:user@example.com?secret=JBSWY3DPEHPK3PXP",
    "qr_code": "data:image/png;base64,..."
  }
}

Display the QR code to the user. They scan it with their authenticator app.

Verify MFA

After enrollment, verify with a code from the authenticator:

bash

curl -X POST https://api.scalix.world/v1/auth/mfa/verify \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"factor_id": "fac_abc123", "code": "123456"}'

Login with MFA

When MFA is enabled, login returns a challenge requiring a second factor:

json

{
  "mfa_required": true,
  "factors": [{"id": "fac_abc123", "type": "totp", "friendly_name": "My Phone"}]
}

Complete the challenge:

bash

curl -X POST https://api.scalix.world/v1/auth/mfa/challenge \
  -d '{"factor_id": "fac_abc123", "code": "123456"}'