Skip to content

Home

Jump to bottom
Helitha Guruge edited this page Nov 30, 2025 · 8 revisions

3xui-api-client Documentation

Welcome to the comprehensive documentation for 3xui-api-client v2.1 - a secure, feature-rich Node.js library for programmatic management of 3x-ui VPN panels with built-in credential generation, advanced session management, and enterprise-grade security.

🚀 Quick Start

Installation

npm install 3xui-api-client

Basic Usage

const ThreeXUI = require('3xui-api-client');

// Initialize with security enhancements
const client = new ThreeXUI(
    'https://your-3xui-server.com',
    'your-username',
    'your-password',
    {
        // Security options
        maxRequestsPerMinute: 60,
        maxLoginAttemptsPerHour: 10,
        isDevelopment: false,
        enableCSP: true,
        
        // Session management (optional)
        sessionManager: {
            type: 'redis',  // or 'memory', 'database'
            redis: redisClient
        }
    }
);

// Create a client with auto-generated credentials (NEW!)
const result = await client.addClientWithCredentials(inboundId, 'vless', {
    email: 'user_example_001'  // Optional - will auto-generate if not provided
});

console.log('Client created:', result.credentials);
// Output: Complete VLESS config with UUID, email, flow settings, etc.

⚠️ Important: This library is server-side only due to session cookie security requirements.

✨ What's New in v2.1

🖥️ Server & Panel Management

  • Full Server Control - Monitor CPU/RAM, restart services, and manage Xray core
  • Panel Settings - Update panel configuration, admin users, and backup settings
  • Database Management - Import/Export database and manage backups
  • Log Access - Retrieve Panel and Xray logs programmatically

🔐 Automatic Credential Generation

  • Zero configuration - Generate secure UUIDs, passwords, and keys automatically
  • All protocols supported - VLESS, VMess, Trojan, Shadowsocks, WireGuard, etc.
  • Production-ready defaults - Secure ciphers, optimal settings out of the box
  • Bulk generation - Create multiple clients with one call

🛡️ Enterprise Security

  • Rate limiting - Configurable request and login attempt limits
  • Input validation - Automatic sanitization of all inputs
  • Secure error handling - Sanitized error messages in production
  • Security monitoring - Track suspicious activities and blocked IPs
  • Secure headers - Content Security Policy, XSS protection, etc.

🔄 Advanced Session Management

  • Auto-renewal - Sessions refresh automatically before expiry
  • Multiple storage options - Memory, Redis, Database, or custom handlers
  • Race condition protection - Mutex-protected login operations
  • Database integration - Built-in SQL session store with cleanup

🌐 Web Integration Ready

  • Express middleware - Ready-to-use proxy for web applications
  • React hooks - Simplified state management for React apps
  • Next.js helpers - API route handlers with session management
  • CORS handling - Secure proxy implementation for browser apps

🔒 Security Overview

Built-in Security Features

✅ Automatic Session Management

  • Sessions expire after 1 hour with auto-renewal
  • Secure cookie handling with HttpOnly flags
  • Rate limiting with configurable IP blocking
  • Session security monitoring and anomaly detection

✅ Input Validation & Sanitization

  • URL validation and sanitization
  • Username/password validation with complexity checking
  • Client and inbound configuration validation
  • Protocol validation with secure defaults
  • Port range validation (1-65535)

✅ Rate Limiting & Monitoring

  • Configurable rate limits (60 requests/minute default)
  • Login attempt limiting (10 attempts/hour default)
  • Automatic IP blocking for abuse patterns
  • Suspicious activity logging and alerts
  • Security event monitoring dashboard

✅ HTTP Security Headers

  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • X-XSS-Protection: 1; mode=block
  • Referrer-Policy: strict-origin-when-cross-origin
  • Content Security Policy (configurable)
  • Cache-Control: no-cache, no-store

✅ Credential Security

  • Secure credential strength validation
  • Cryptographic session tokens
  • Secure logging with data redaction
  • Password complexity checking
  • UUID format validation and generation

✅ Production-Ready Error Handling

  • Sanitized error messages in production mode
  • Sensitive data redaction from logs
  • Development/production mode switching
  • Generic error responses for security
  • Secure error logging patterns

Security Best Practices Included

  • Server-side only - Never use in browser applications
  • Environment variables - Credential storage best practices
  • Session storage - Redis/Database integration for scalability
  • Access controls - Built-in rate limiting and IP blocking
  • Audit trails - Comprehensive security event logging

📚 Core Documentation

🔐 Authentication Guide

Session management, security best practices, and database integration patterns.

  • Auto-login and session renewal
  • Multiple storage backends (Redis, Database, Memory)
  • Security monitoring and rate limiting

🛠️ Inbound Management

Complete guide to managing VPN server configurations with auto-generation.

  • Protocol builders (VLESS, VMess, Trojan, Shadowsocks)
  • Auto-generated security configurations
  • Port and network management

👥 Client Management

User account operations with automatic credential generation.

  • Auto-generated UUIDs and passwords
  • Bulk client creation and management
  • Traffic limits and IP restrictions

Note: In 3x-ui, the email field is a client identifier, not an email address. See the note in the Client Management guide.

📊 Traffic Management

Monitor and control data usage with real-time capabilities.

  • Real-time traffic monitoring
  • Automated usage limits and resets
  • Bulk cleanup operations

🖥️ System Operations

Administrative operations and system maintenance with security features.

  • Online client monitoring
  • Secure backup operations
  • Health checking and diagnostics

💡 Use Cases & Examples

Real-world implementation examples with web integration patterns.

  • VPN service provider automation
  • Web application integration
  • Real-time monitoring dashboards
  • Security best practices

🎯 API Reference

Enhanced Authentication (Auto-managed)

// Automatic login with session persistence
const client = new ThreeXUI(url, username, password, {
    sessionManager: { redis: redisClient }  // Auto-handles sessions
});

// Sessions are handled automatically - no manual login needed!
const inbounds = await client.getInbounds();  // Auto-authenticates if needed

Credential Generation (NEW!)

// Generate credentials for any protocol
const vlessCredentials = client.generateCredentials('vless');
const trojanCredentials = client.generateCredentials('trojan');
const bulkCredentials = client.generateBulkCredentials('vless', 10);

// Create clients with auto-generated credentials
const client = await api.addClientWithCredentials(inboundId, 'vless', {
    email: 'custom_user_123'  // Optional
});
// Auto-generates: UUID, flow settings, security config, etc.

Security Methods (NEW!)

// Monitor security events
const stats = client.getSecurityStats();
console.log('Blocked IPs:', stats.blockedIPs);
console.log('Suspicious activities:', stats.recentActivities);

// Validate credential strength
const validation = client.validateCredentialStrength('myPassword123', 'password');
if (!validation.isValid) {
    console.error('Weak credentials:', validation.issues);
}

// Clear security blocks (admin function)
client.clearBlockedIPs();

All Available Methods (24+ total)

// Authentication (Auto-managed)
await client.login()  // Usually not needed - auto-called

// Credential Generation (NEW!)
client.generateCredentials(protocol, options)
client.generateBulkCredentials(protocol, count, options)
client.generateUUID(secure)
client.generatePassword(length, options)

// Enhanced Client Operations
await client.addClientWithCredentials(inboundId, protocol, options)  // NEW!
await client.updateClientWithCredentials(clientId, inboundId, options)  // NEW!
await client.addClient(config)
await client.updateClient(clientId, config)
await client.deleteClient(inboundId, clientId)

// Inbound Operations (Enhanced with validation)
await client.getInbounds()
await client.getInbound(id)
await client.addInbound(config)  // Now with input validation
await client.updateInbound(id, config)  // Now with input validation
await client.deleteInbound(id)

// Traffic Operations
await client.getClientTrafficsByEmail(email)
await client.getClientTrafficsById(id)
await client.resetClientTraffic(inboundId, email)
await client.resetAllTraffics()
await client.resetAllClientTraffics(inboundId)
await client.deleteDepletedClients(inboundId)

// System Operations
await client.getOnlineClients()
await client.createBackup()
await client.getClientIps(email)
await client.clearClientIps(email)

// Security Operations (NEW!)
await client.getSecurityStats()
await client.clearBlockedIPs()
await client.validateCredentialStrength(credential, type)
await client.generateSecureToken()
await client.setDevelopmentMode(enabled)

🛡️ Security Features

Built-in Security Enhancements

  • ✅ Rate Limiting - 60 requests/minute, 10 login attempts/hour (configurable)
  • ✅ Input Validation - All inputs sanitized and validated
  • ✅ Secure Headers - CSP, XSS protection, content type validation
  • ✅ Error Sanitization - Sensitive data redacted in production
  • ✅ IP Blocking - Automatic blocking of suspicious activities
  • ✅ Session Security - Encrypted storage with auto-renewal

Example Secure Configuration

const client = new ThreeXUI(url, username, password, {
    // Stricter security settings
    maxRequestsPerMinute: 30,
    maxLoginAttemptsPerHour: 5,
    isDevelopment: false,           // Production mode
    enableCSP: true,               // Content Security Policy
    timeout: 15000,                // 15 second timeout
    
    // Enterprise session management
    sessionManager: {
        type: 'database',
        database: dbConnection,
        tableName: 'xui_sessions',
        defaultTTL: 3600,
        autoRefresh: true
    }
});

🔧 Web Integration Examples

Express.js Backend

const express = require('express');
const ThreeXUI = require('3xui-api-client');

const app = express();
const xui = new ThreeXUI(url, username, password, {
    sessionManager: { redis: redisClient }
});

// Secure API endpoint
app.post('/api/create-client', async (req, res) => {
    try {
        const result = await xui.addClientWithCredentials(
            req.body.inboundId,
            'vless',
            { email: req.body.clientId }
        );
        res.json(result);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

Next.js API Route

// pages/api/3xui/create-client.js
import { ThreeXUI } from '3xui-api-client';

const xui = new ThreeXUI(
    process.env.XUI_URL,
    process.env.XUI_USERNAME,
    process.env.XUI_PASSWORD,
    { sessionManager: { database: db } }
);

export default async function handler(req, res) {
    const client = await xui.addClientWithCredentials(
        req.body.inboundId,
        'vless'
    );
    res.json(client);
}

🚀 Protocol Support

Supported Protocols (9 total)

  1. VLESS - UUID authentication with Reality/XTLS support
  2. VMess - UUID authentication (legacy V2Ray)
  3. Trojan - Password-based with TLS
  4. Shadowsocks - Password + cipher method
  5. Shadowsocks2022 - Enhanced with modern AEAD
  6. WireGuard - Public/private key pairs
  7. SOCKS5 - Username/password (optional)
  8. HTTP - Basic auth (optional)
  9. Dokodemo-door - No authentication (port forwarding)

Auto-Generated Defaults

  • VLESS: UUID + xtls-rprx-vision flow + Reality config
  • Trojan: 16-char secure password + TLS settings
  • Shadowsocks: chacha20-ietf-poly1305 cipher + secure password
  • WireGuard: Curve25519 key pairs + client config

🔧 Troubleshooting

Common Issues

Authentication Errors

  • Check rate limiting: client.getSecurityStats()
  • Verify credentials and server accessibility
  • Review security logs: ErrorSecurity.logError()

Session Problems

  • Sessions auto-refresh at 80% expiration
  • Check session store connectivity (Redis/Database)
  • Monitor with client.getSessionStats()

Web Integration Issues

  • Use server-side proxy for browser applications
  • Implement proper CORS handling
  • Store sessions securely server-side only

Getting Help

📦 Package Information

  • Current Version: 2.0.0
  • License: MIT
  • Node.js Support: 16.0.0+
  • Security Enhanced: ✅ Enterprise-grade security features
  • Web Integration: ✅ Express, Next.js, React ready
  • GitHub: iamhelitha/3xui-api-client
  • npm: 3xui-api-client

Navigation

Previous Next
- Authentication Guide →

Last updated: September 2025

Clone this wiki locally