Skip to content

Home

Jump to bottom
Helitha Guruge edited this page Jun 15, 2026 · 8 revisions

3xui-api-client Documentation

Welcome to the documentation for 3xui-api-client v3.1.0 — a Node.js client library for managing 3x-ui VPN panels. Supports both API token authentication (3x-ui v3.0.2+) and legacy cookie-based login, with 124 API routes, built-in credential generation, session management, and enterprise security.

Quick Start

Installation

npm install 3xui-api-client

Cookie-based login (all 3x-ui versions)

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

const client = new ThreeXUI(
    'https://your-panel.com:2053',
    'admin',
    'your-password'
);

const inbounds = await client.getInbounds(); // auto-authenticates

API token authentication (3x-ui v3.0.2+)

const client = new ThreeXUI('https://your-panel.com:2053', {
    token: 'your-api-token-here'
});

// No login() needed — token is sent on every request
const inbounds = await client.getInbounds();

Server-side only. Never use this library in browser/client-side code — session cookies and tokens are sensitive credentials.

What's New in v3.1.0

🔄 Dual Panel Support

Fully supports both modern (React-based) and legacy (Vue-based) 3x-ui panels. The client automatically detects the panel version on first login (with seamless fallback) and caches it in the session. You can also enforce a version using { panelVersion: 'modern' | 'legacy' } in options.

🔑 API Token Authentication

Pass token or apiToken in options to authenticate with Bearer token headers instead of cookie login. Required for 3x-ui v3.0.2+ where the panel enforces token-based access for API operations.

📡 48 New Modern API Routes (3x-ui v2.x/v3.x)

Full coverage of the modern /panel/api/clients/, /panel/api/nodes/, and /panel/api/custom-geo/ endpoints. See Modern API Guide.

🔄 Flexible Constructor

Three equivalent ways to initialize the client:

// Original positional style (unchanged)
new ThreeXUI(url, username, password)
new ThreeXUI(url, username, password, options)

// New object style
new ThreeXUI(url, { username, password })
new ThreeXUI(url, { token: 'api-token' })

Documentation

Guide Description
Authentication Guide Cookie login, API token auth, session management, security
Modern API Guide All 48 new routes — Clients, Groups, Nodes, Custom Geo
Inbound Management Create and manage VPN server inbounds
Client Management User accounts, credential generation, bulk operations
Traffic Management Monitor and reset traffic, manage depleted clients
System Operations Server status, Xray config, panel settings, backups
Use Cases Real-world examples and integration patterns

Full API Reference

Authentication

await client.login(forceRefresh?)      // Cookie auth — usually called automatically
await client.logout()                  // Clear session and cookie
await client.getTwoFactorEnable()      // Check if 2FA is enabled
await client.isSessionValid()          // Returns true if session or token is active
await client.getSessionStats()         // Session cache statistics
await client.clearAllSessions()        // Clear all cached sessions

Modern API — Clients (3x-ui v2.x/v3.x)

// Read
await client.getClients()
await client.getPagedClients({ page, size, sort, order, email })
await client.getClient(email)
await client.getClientTraffic(email)
await client.getSubLinks(subId)
await client.getClientLinks(email)
await client.getModernClientIps(email)
await client.getOnlines()
await client.getModernLastOnline()

// Write
await client.addModernClient(data)
await client.updateModernClient(email, data)
await client.deleteModernClient(email)
await client.attachClientToInbounds(email, data)
await client.detachClientFromInbounds(email, data)
await client.resetModernClientTrafficByEmail(email)
await client.updateModernClientTrafficByEmail(email, data)
await client.clearModernClientIps(email)
await client.resetAllModernClientTraffics()
await client.deleteDepletedModernClients()

// Bulk
await client.bulkCreateModernClients(data)
await client.bulkAdjustModernClients(data)
await client.bulkDeleteModernClients(data)
await client.bulkAttachModernClients(data)
await client.bulkDetachModernClients(data)
await client.bulkResetTrafficModernClients(data)

Modern API — Client Groups

await client.getGroups()
await client.getGroupEmails(groupName)
await client.createGroup(data)
await client.renameGroup(data)
await client.deleteGroup(data)
await client.bulkAddGroups(data)
await client.bulkRemoveGroups(data)

Modern API — Nodes

await client.getNodes()
await client.getNode(id)
await client.getNodeHistory(id, metric, bucket)
await client.addNode(data)
await client.updateNode(id, data)
await client.deleteNode(id)
await client.setNodeEnable(id)
await client.testNode(data)
await client.probeNode(id)

Modern API — Custom Geo

await client.getCustomGeos()
await client.getGeoAliases()
await client.addCustomGeo(data)
await client.updateCustomGeo(id, data)
await client.deleteCustomGeo(id)
await client.downloadCustomGeo(id)
await client.updateAllCustomGeo()

Inbounds (all 3x-ui versions)

await client.getInbounds()
await client.getInbound(id)
await client.addInbound(config)
await client.updateInbound(id, config)
await client.deleteInbound(id)
await client.importInbounds(inbounds) // accepts a single config or an array; returns an array of results

Clients — Legacy API (older Vue-based panels only)

⚠️ v3.x panels (React-based) have removed these /panel/api/inbounds/* client routes - use the Modern Client API instead (addModernClient, updateModernClient, deleteModernClient, getClientTraffic, getModernClientIps, clearModernClientIps, getModernLastOnline, getOnlines, etc). These legacy methods only work on older, pre-v3.x panels.

await client.addClient(config)
await client.updateClient(clientId, config)
await client.deleteClient(inboundId, clientId)
await client.deleteClientByEmail(inboundId, email)
await client.updateClientTraffic(email, trafficConfig)
await client.getClientTrafficsByEmail(email)
await client.getClientTrafficsById(id)
await client.getClientIps(email)
await client.clearClientIps(email)
await client.getLastOnline()
await client.getOnlineClients()

// Auto-credential helpers
await client.addClientWithCredentials(inboundId, protocol, options)
await client.updateClientWithCredentials(clientId, inboundId, options)

Traffic

await client.resetAllTraffics() // all 3x-ui versions - resets traffic for ALL clients

// Legacy API - older Vue-based panels only (removed in v3.x, use Modern API equivalents)
await client.resetClientTraffic(inboundId, email)
await client.resetAllClientTraffics(inboundId)
await client.deleteDepletedClients(inboundId)

System

await client.backupToTgBot()
await client.getServerStatus()
await client.getCPUHistory(bucket?)
await client.getXrayVersion()
await client.getConfigJson()
await client.getDb()
await client.stopXrayService()
await client.restartXrayService()
await client.installXray(version)
await client.getPanelLogs(count?)
await client.getXrayLogs(count?)
await client.updateGeofile(fileName?)
await client.importDB(formData)

Panel Settings

await client.getAllSettings()
await client.updateSetting(settings)
await client.updateUser(oldUsername, oldPassword, newUsername, newPassword)
await client.restartPanel()
await client.getDefaultSettings()
await client.getDefaultJsonConfig()

Xray Configuration

await client.getXrayConfig()
await client.updateXrayConfig(config)
await client.manageWarp(action, data?)
await client.getOutboundsTraffic()
await client.resetOutboundsTraffic()
await client.getXrayResult()

Server-Side Generators

await client.getNewUUID()
await client.getNewX25519Cert()
await client.getNewmldsa65()
await client.getNewmlkem768()
await client.getNewVlessEnc()
await client.getNewEchCert()

Credential Generation (local, no network)

client.generateCredentials(protocol, options)
client.generateBulkCredentials(protocol, count, options)
client.generateUUID(secure?)
client.generatePassword(length?, options?)
client.generateWireGuardKeys()
client.generateRealityKeys()
client.generatePort(min?, max?)
client.validateCredentials(credentials, protocol)
client.getShadowsocksCiphers()
client.getRecommendedShadowsocksCipher()

Security

client.getSecurityStats()
client.clearBlockedIPs()
client.validateCredentialStrength(credential, type)
client.generateSecureToken()
client.setDevelopmentMode(enabled)

Package Information
Version 3.1.0
License MIT
Node.js ≥ 16.0.0
3x-ui compatibility All versions (token auth requires v3.0.2+)
npm 3xui-api-client
GitHub iamhelitha/3xui-api-client

Last updated: June 2026

Clone this wiki locally