Overview
This guide provides comprehensive documentation for front-end developers integrating with the Rcoinx MFA (Multi-Factor Authentication) client-side handlers. The MFA system provides enterprise-grade security through multiple authentication methods including TOTP, SMS, Email, and WebAuthn.This guide focuses on client-side API handlers. For general MFA concepts and flows, see the MFA Overview.
Base URL
All endpoints are prefixed with/api/auth/mfa:
Core Concepts
MFA Methods
The system supports multiple MFA methods:- TOTP (
totp): Time-based One-Time Password using authenticator apps (Google Authenticator, Authy, etc.) - SMS (
sms): SMS-based OTP codes sent to user’s mobile phone - Email (
email): Email-based OTP codes sent to user’s email address - WebAuthn (
webauthn): Passwordless authentication using biometrics or security keys - Backup Codes (
backup_code): One-time use backup codes for account recovery
MFA Status
Users can have three MFA statuses:- Disabled: MFA is not enabled
- Enabled: MFA is enabled but optional
- Required: MFA is required for certain actions
MFA Sessions
MFA sessions are temporary tokens created for specific actions that require MFA verification. Sessions:- Are tied to specific actions (e.g.,
transfer_funds,change_password) - Have expiration times (typically 5 minutes)
- Track verification progress across multiple MFA methods
- Can be validated, extended, or cancelled
Authentication
All MFA endpoints require JWT authentication. Include the JWT token in the Authorization header:API Endpoints
MFA Methods
Get All Available MFA Methods
Retrieve all MFA methods available to users. Response:200 OK
Get Specific MFA Method
Retrieve details for a specific MFA method by ID. Parameters:id(path): MFA method ID
200 OK
User MFA Configuration
Get User MFA Status
Retrieve the current MFA configuration and status for the authenticated user. Response:200 OK
Enable MFA
Enable a specific MFA method for the user. Note: You must first set up the MFA method (e.g., via TOTP setup, email verification) before enabling it. Request:200 OK
Disable MFA
Disable a specific MFA method for the user. Request:200 OK
MFA Sessions
Create MFA Session
Create a new MFA session for a specific action. Request:200 OK
MFA sessions expire after 5 minutes by default. If
requires_mfa is false, the action doesn’t require MFA and can proceed without verification.Validate MFA Session
Check if an MFA session is valid and not expired. Request:200 OK
Verify MFA Code
Verify an MFA code for a session. This is the core verification step. Request:200 OK
Cancel MFA Session
Cancel an active MFA session. Request:200 OK
Get Active MFA Sessions
Retrieve all active MFA sessions for the authenticated user. Response:200 OK
Send Code to User
Request a code to be sent via SMS or Email for MFA verification. Request:200 OK
MFA Validation
Check MFA Requirement
Check if MFA is required for a specific action. Request:200 OK
MFA Scopes and Actions
Get MFA Scopes
Retrieve all available MFA scopes. Response:200 OK
Get MFA Actions
Retrieve all available MFA actions. Response:200 OK
TOTP Setup and Verification
Setup TOTP
Generate a TOTP secret and get the QR code URL for setup. Response:200 OK
Verify and Enable TOTP
Verify a TOTP code from the authenticator app and enable TOTP MFA. Request:200 OK
Verify TOTP Code
Verify a TOTP code during MFA verification (e.g., during login or action verification). Request:200 OK
Email MFA Setup and Verification
Send Email Verification OTP
Send an OTP code to the user’s email address for MFA setup. Request:200 OK
Verify and Enable Email MFA
Verify the email OTP code and enable email MFA. Request:200 OK
SMS MFA Setup and Verification
Send Mobile Verification OTP
Send an OTP code to the user’s mobile phone for MFA setup. Request:200 OK
Verify and Enable SMS MFA
Verify the mobile OTP code and enable SMS MFA. Request:200 OK
WebAuthn Setup and Verification
Setup WebAuthn
Begin WebAuthn registration ceremony and get credential creation options. Response:200 OK
For detailed WebAuthn implementation, see the WebAuthn Guide.
Complete Integration Examples
Example 1: Complete TOTP Setup Flow
Example 2: Action-Based MFA Verification Flow
Example 3: React Hook for MFA Management
Error Handling
Common Error Responses
All endpoints return errors in a consistent format:HTTP Status Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad Request - Invalid parameters or request format |
| 401 | Unauthorized - Invalid or missing JWT token |
| 403 | Forbidden - Action not allowed |
| 404 | Not Found - Resource not found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Server error |
Error Handling Example
Best Practices
1. Security
- Never store MFA secrets or codes in localStorage or sessionStorage
- Always use HTTPS in production
- Validate all user inputs on the client side before sending
- Implement rate limiting on the client side to prevent abuse
- Clear sensitive data from memory after use
2. User Experience
- Provide clear instructions for each MFA method
- Show progress indicators during MFA setup and verification
- Display helpful error messages
- Allow users to cancel MFA operations
- Provide fallback options if primary MFA method fails
3. Error Handling
- Always handle network errors gracefully
- Provide retry mechanisms for failed requests
- Show user-friendly error messages
- Log errors for debugging but don’t expose sensitive information
4. Session Management
- Validate session tokens before use
- Handle session expiration gracefully
- Cancel unused sessions to free resources
- Store session tokens securely (not in localStorage)
Troubleshooting
Common Issues
”User ID not found in token” Error
Problem: JWT token is invalid or expired. Solution:- Check if the token is valid
- Refresh the token if it’s expired
- Ensure the token is being sent in the Authorization header
”MFA session expired” Error
Problem: MFA session has expired (default 5 minutes). Solution:- Create a new MFA session
- Complete verification within the session timeout
”Invalid MFA code” Error
Problem: The provided code is incorrect or expired. Solution:- For TOTP: Ensure the device time is synchronized
- For SMS/Email: Request a new code if the previous one expired
- Check if the code format is correct (6 digits for most methods)
Rate Limiting
Problem: Too many requests in a short time. Solution:- Implement exponential backoff
- Show user-friendly message about rate limiting
- Wait for the rate limit window to reset
Related Documentation
- MFA Overview - General MFA concepts and flows
- WebAuthn Guide - Detailed WebAuthn implementation
- SMS OTP - SMS verification details
- Authentication - Login and token management