Multi-Factor Authentication

TOTP Setup

POST /v1/auth/mfa/totp/setup

Requires an active session. Returns the TOTP secret, QR code URL, and backup codes.

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code_url": "otpauth://totp/Zautha:user@example.com?secret=...",
  "backup_codes": ["abc123", "def456", "..."]
}

TOTP Verify (Setup)

POST /v1/auth/mfa/totp/verify

Confirms TOTP setup by verifying the first code from the authenticator app.

{ "code": "123456" }

SMS Setup

POST /v1/auth/mfa/sms/setup

{ "phone_number": "+1234567890" }

Sends a verification SMS to the provided phone number.

SMS Verify (Setup)

POST /v1/auth/mfa/sms/verify

{ "code": "123456" }

When sign-in returns mfa_required: true, use this endpoint to complete authentication:

POST /v1/auth/mfa/verify

{
  "mfa_token": "mfa_xxx",
  "factor": "totp",
  "code": "123456"
}

Response 200:

{
  "user": { "id": "...", "email": "..." },
  "session": { "id": "...", "access_token": "..." }
}

SDK Usage

import { useAuth } from '@zautha/react';
import { isMfaChallenge } from '@zautha/sdk';

function SignInForm() {
  const { signIn, verifyMfa } = useAuth();

  const handleSignIn = async (email, password) => {
    const result = await signIn({ identifier: email, password });

    if (isMfaChallenge(result)) {
      // Show MFA input, then:
      await verifyMfa({
        mfaToken: result.mfa_token,
        factor: 'totp',
        code: userEnteredCode,
      });
    }
  };
}