​
Overview

The User Management module is the core authentication and user identity system for RcoinX. It provides a complete suite of features for user registration, authentication, profile management, and advanced security features including multi-factor authentication (MFA), WebAuthn, and OAuth integrations.

​
Module Architecture

The User Management module is built with a modular architecture consisting of the following components: 
/api/auth
├── /auth                    # Core authentication & profile
├── /auth/mfa               # Multi-factor authentication
├── /auth/webauthn          # WebAuthn (passkeys/biometrics)
├── /auth/sms-otp           # SMS OTP verification
├── /auth/sessions          # Session & activity management
├── /auth/register          # Registration flows
├── /auth/forget-password   # Password recovery
└── /oauth                  # OAuth provider integrations

​
Key Features

​
1. Core Authentication

  • Email and phone number-based registration
  • Secure login with JWT tokens
  • Token refresh mechanism
  • Remember me functionality
  • Password management
  • Account freeze/unfreeze
  • Account deletion

​
2. Profile Management

  • User profile CRUD operations
  • Profile image upload/delete
  • Email and phone number management
  • Username updates
  • Metadata support

​
3. Multi-Factor Authentication (MFA)

  • TOTP (Time-based One-Time Password)
  • Email OTP
  • SMS OTP
  • Action-based MFA requirements
  • Backup codes
  • Multiple MFA method support

​
4. WebAuthn Support

  • Passkey registration
  • Biometric authentication
  • Hardware security key support
  • Credential management

​
5. OAuth Integration

  • Google OAuth
  • Telegram OAuth
  • Multiple provider support
  • Account linking/unlinking

​
6. Session Management

  • Active session tracking
  • Multi-device session management
  • Remote logout
  • Login activity history
  • Session statistics

​
7. Security Features

  • Rate limiting on sensitive endpoints
  • Audit logging
  • Login attempt tracking
  • IP-based tracking
  • User agent detection

​
Base URL

All User Management APIs are accessible under the base URL: 
https://api.rcoinx.com/api
For local development: 
http://localhost:8080/api

​
Authentication

Most endpoints require authentication using JWT Bearer tokens. Include the access token in the Authorization header: 
Authorization: Bearer <access_token>

​
Token Types

  1. Access Token: Short-lived token for API requests (default: 15 minutes)
  2. Refresh Token: Long-lived token for obtaining new access tokens (default: 7 days)
  3. Remember Me Token: Extended refresh token (default: 30 days)

​
Token Refresh Flow

When an access token expires, use the refresh token to obtain a new access token: 
const response = await fetch('https://api.rcoinx.com/api/refresh', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${refreshToken}`
  }
});

const { data } = await response.json();
const newAccessToken = data.access_token;

​
Response Format

All API responses follow a consistent format:

​
Success Response

{
  "code": 200,
  "message": "Success message",
  "data": {
    // Response data
  }
}

​
Error Response

{
  "code": 400,
  "message": "Error message",
  "error": "Detailed error description"
}

​
Common HTTP Status Codes

Status CodeDescription
200Success
201Created
400Bad Request - Invalid input
401Unauthorized - Invalid or expired token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
409Conflict - Resource already exists
422Unprocessable Entity - Validation error
429Too Many Requests - Rate limit exceeded
500Internal Server Error
503Service Unavailable

​
Error Handling

Implement proper error handling in your frontend application: 
async function makeRequest(url, options) {
  try {
    const response = await fetch(url, options);
    const data = await response.json();
    
    if (!response.ok) {
      // Handle specific error codes
      switch (response.status) {
        case 401:
          // Redirect to login or refresh token
          await refreshAccessToken();
          break;
        case 429:
          // Show rate limit message
          showError('Too many requests. Please try again later.');
          break;
        default:
          showError(data.message || 'An error occurred');
      }
      throw new Error(data.message);
    }
    
    return data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

​
Rate Limiting

The API implements rate limiting on sensitive endpoints:
  • MFA Verification: 5 attempts per minute
  • MFA General Operations: Configurable (default: 100 requests per minute)
  • Code Generation: Rate limited per endpoint
When rate limit is exceeded, the API returns a 429 Too Many Requests status code.

​
Data Validation

All request payloads are validated. Common validation rules:
  • Email: Must be valid email format
  • Phone: Minimum 10 digits, numeric only
  • Country Code: 1-3 digits
  • Password: Minimum 8 characters
  • Username: 3-50 characters, unique

​
Metadata Support

Many entities support a meta_data field for storing custom JSON data: 
{
  "meta_data": "{\"theme\": \"dark\", \"language\": \"en\", \"notifications\": true}"
}

​
Next Steps

Explore the detailed API documentation for each component:

Authentication APIs

Login, register, and token management

Profile Management

User profile operations and settings

MFA

Multi-factor authentication setup and verification

WebAuthn

Passkey and biometric authentication

OAuth

Third-party provider integration

Session Management

Session tracking and login activity

​
SDK & Libraries

While you can make direct HTTP requests, we recommend using standard HTTP clients: 
// Using fetch API
const response = await fetch('https://api.rcoinx.com/api/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
});

const data = await response.json();

​
Support

For questions and support: