WireGuard API Client

A robust Node.js client library for interacting with the WireGuard API, designed for WG-Easy servers

npm version GitHub license GitHub issues Downloads
Get Started View on GitHub

Русский | Русский

WireGuard Logo

Features

Powerful tools for managing your WireGuard VPN

Automatic Session Management

Handles retries on 401 errors automatically

Full API Coverage

Complete implementation of WG-Easy endpoints

Flexible Authentication

Supports both password and cookie-based auth

Structured Error Handling

Detailed error responses for easy debugging

TypeScript Support

Comprehensive type definitions included

Installation & Requirements

Get started with the WireGuard API Client

npm install wg-easy-api
  • Node.js 12.x or higher
  • node-fetch (^3.3.2) - Included as a dependency
  • A running WG-Easy server (typically on port 51821)

Usage Examples

Learn how to use the WireGuard API Client

const WireGuardAPI = require('wg-easy-api');

async function example() {
    const api = new WireGuardAPI('https', 'example.com', 51821, 'your-password');
    try {
        const auth = await api.initSession({ password: 'your-password' });
        console.log(auth);
        const clients = await api.getClients();
        console.log('Clients:', JSON.stringify(clients, null, 2));
    } catch (error) {
        console.error('Error:', JSON.parse(error.message));
    }
}

example();
const api = new WireGuardAPI('https', 'example.com', 51821, undefined, 'connect.sid=s%3A...');
const clients = await api.getClients();
console.log(clients);
try {
    const clients = await api.getClients();
} catch (error) {
    const err = JSON.parse(error.message);
    console.error(err.error, err.statusCode);
}

API Reference

Complete documentation for all methods

Response Format

Session Management

POST /api/session

Logs into the WG-Easy server with a password. Updates cookies automatically.

Parameter Type Required Description
password string Yes WG-Easy password 
await api.initSession({ password: 'myPass' }); // { status: 'success', data: { success: true } }
GET /api/session

Checks current session status.

await api.getSession(); // { status: 'success', data: { authenticated: true } }
POST /api/session

Creates a new session without auto-updating cookies.

Parameter Type Required Description
password string Yes WG-Easy password 
await api.createSession({ password: 'myPass' });
DELETE /api/session

Logs out by deleting the session.

await api.deleteSession(); // { status: 'success', data: null }

Client Operations

GET /api/wireguard/client

Lists all WireGuard clients, converting timestamps to Date objects.

await api.getClients(); // { status: 'success', data: [{ id: 'abc', name: 'Client1' }] }
POST /api/wireguard/client

Adds a new client with the given name.

Parameter Type Required Description
name string Yes Client name 
await api.createClient({ name: 'MyLaptop' });
DELETE /api/wireguard/client/{clientId}

Removes a client by ID.

Parameter Type Required Description
clientId string Yes Client ID 
await api.deleteClient({ clientId: 'abc' });
POST /api/wireguard/client/{clientId}/enable

Enables a client to connect.

Parameter Type Required Description
clientId string Yes Client ID 
await api.enableClient({ clientId: 'abc' });
POST /api/wireguard/client/{clientId}/disable

Disables a client.

Parameter Type Required Description
clientId string Yes Client ID 
await api.disableClient({ clientId: 'abc' });
PUT /api/wireguard/client/{clientId}/name

Changes a client’s name.

Parameter Type Required Description
clientId string Yes Client ID
name string Yes New name 
await api.updateClientName({ clientId: 'abc', name: 'NewName' });
PUT /api/wireguard/client/{clientId}/address

Updates a client’s IP address.

Parameter Type Required Description
clientId string Yes Client ID
address string Yes New IP address 
await api.updateClientAddress({ clientId: 'abc', address: '10.0.0.3' });

Configuration and QR Code

GET /api/wireguard/client/{clientId}/configuration

Gets a client’s .conf file as text.

Parameter Type Required Description
clientId string Yes Client ID 
await api.getClientConfig({ clientId: 'abc' }); // { status: 'success', data: '[Interface]...' }
GET /api/wireguard/client/{clientId}/qrcode.svg

Gets a client’s config as an SVG QR code.

Parameter Type Required Description
clientId string Yes Client ID 
await api.getClientQRCode({ clientId: 'abc' }); // { status: 'success', data: '...' }
PUT /api/wireguard/restore

Restores a server config from a string.

Parameter Type Required Description
file string Yes Configuration file content 
await api.restoreConfiguration('[Interface]...');

Miscellaneous

GET /api/release

Gets the WG-Easy version.

await api.getRelease(); // { status: 'success', data: { version: '7' } }
GET /api/lang

Gets the UI language.

await api.getLang(); // { status: 'success', data: { lang: 'en' } }
GET /api/ui-traffic-stats

Gets traffic stats.

await api.getUITrafficStats(); // { status: 'success', data: { bytesSent: 12345 } }
GET /api/ui-chart-type

Gets the UI chart type.

await api.getChartType(); // { status: 'success', data: { type: 'line' } }

Debugging Tips

Copied to clipboard!