SMS Verification

Production - POST /api/v1/mfa/sms/enroll, POST /api/v1/mfa/sms/verify, POST /api/v1/mfa/sms/resend

SMS MFA sends a verification code to the user's registered phone number via Twilio. Enrollment requires verifying the phone number before it can be used for login MFA challenges.

6.3.3SMS Enrollment Flow

Step 1: Initiate SMS Enrollment

curl -X POST http://localhost:8081/api/v1/mfa/sms/enroll \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+1234567890" }'

Response (200 OK)

{
  "maskedPhoneNumber": "****7890",
  "codeSent": true,
  "expiresInSeconds": 300,
  "retryAfterSeconds": 60
}

Step 2: Verify SMS Code

curl -X POST http://localhost:8081/api/v1/mfa/sms/verify \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "code": "482917" }'

Response (200 OK)

Returns MfaTotpEnrollmentResponse with enrolled: true and backup codes.

Resend Code

curl -X POST http://localhost:8081/api/v1/mfa/sms/resend \
  -H "Authorization: Bearer <access-token>"

Subject to rate limiting (one code per 60 seconds).

Disable SMS MFA

curl -X DELETE http://localhost:8081/api/v1/mfa/sms \
  -H "Authorization: Bearer <access-token>"

Error Codes

Code	HTTP Status	Description
`SMS_ALREADY_CONFIGURED`	400	SMS MFA is already enrolled
`INVALID_PHONE_NUMBER`	400	Phone number format is invalid
`SMS_RATE_LIMITED`	429	Code resend rate limit exceeded
`MFA_INVALID_CODE`	400	Verification code is incorrect

TOTP Setup Email MFA