wgeasy-sdk

A fully-typed TypeScript client SDK for the wg-easy REST API.

All types come directly from the wg-easy source code.

Features

• Updated to work with wg-easy v15 (Tested version: 15.2.2)
• Full TypeScript types for every request and response
• Cookie-based session auth and HTTP Basic Auth support
• Covers every API endpoint: session, profile, clients, admin, setup
• Thin Axios wrapper; access the raw instance when needed
• Cross support for ESM and CJS (ily require() friends ♥️)

Installation

bun add wgeasy-sdk
# or: npm install wgeasy-sdk
# or: pnpm install wgeasy-sdk
# or: yarn install wgeasy-sdk
# or:- we are gonna be here all day if we contuine...

Quick Start

import { WgEasyClient } from 'wgeasy-sdk';

const wg = new WgEasyClient({ 
  baseUrl: 'http://localhost:51821',
  auth: { username: 'admin', password: 'password' }
});

// List all WireGuard peers
const peers = await wg.clients.list();

// Create a new peer
const { clientId } = await wg.clients.create({
  name: 'my-laptop',
  expiresAt: null,
});

// Download its .conf file
const conf = await wg.clients.getConfiguration(clientId);
console.log(conf);

Authentication

HTTP Basic Auth

Pass credentials at construction time.

const wg = new WgEasyClient({
  baseUrl: 'http://localhost:51821',
  auth: { username: 'admin', password: 'supersecret123' },
});

Session cookies

Login after the client is created.

await wg.session.login({ username: 'admin', password: '...', remember: true });
const user = await wg.session.getUser();
await wg.session.logout();

API Reference

new WgEasyClient(options)

| Option | Type | Description | |---|---|---| | baseUrl | string | Base URL of your wg-easy instance | | auth | { username, password } | Optional HTTP Basic Auth credentials | | timeout | number | Axios timeout in ms (default 10000) |

wg.session - SessionAPI

| Method | Description | |---|---| | login(body) | Log in; returns { status } ('success' or 'TOTP_REQUIRED' or 'INVALID_TOTP_CODE') | | getUser() | Get the currently authenticated user | | logout() | Destroy the session |

wg.me - MeAPI

Manage the authenticated user's profile.

| Method | Description | |---|---| | updateProfile({ name, email }) | Update display name and email | | updatePassword({ currentPassword, newPassword, confirmPassword }) | Change password | | totpSetup() | Begin TOTP setup; returns { key, uri } | | totpCreate(code) | Confirm TOTP with a 6-digit code | | totpDelete(currentPassword) | Remove TOTP from the account |

wg.clients - ClientsAPI

Manage WireGuard peers. ADMINs see all peers; CLIENT-role users see only their own.

| Method | Description | |---|---| | list(query?) | List peers; optional filter string | | get(clientId) | Get a single peer | | create({ name, expiresAt }) | Create a peer; returns { clientId } | | update(clientId, body) | Update full peer configuration | | delete(clientId) | Delete a peer | | enable(clientId) | Allow traffic through the VPN | | disable(clientId) | Block traffic through the VPN | | getConfiguration(clientId) | Download the .conf file as a string | | getQrCodeSvg(clientId) | Get the config QR code as an SVG string | | generateOneTimeLink(clientId) | Create a one-time shareable config link |

wg.admin - AdminAPI

All sub-APIs require the ADMIN role.

wg.admin.general

| Method | Description | |---|---| | get() | Get session timeout and metrics settings | | update(body) | Update session timeout and metrics settings |

wg.admin.hooks

| Method | Description | |---|---| | get() | Get global WireGuard lifecycle hooks (preUp, postUp, preDown, postDown) | | update(body) | Update global WireGuard lifecycle hooks |

wg.admin.interface

| Method | Description | |---|---| | get() | Get interface configuration (CIDR, port, MTU, firewall, obfuscation) | | update(body) | Update interface settings | | updateCidr({ ipv4Cidr, ipv6Cidr }) | Reassign IP address blocks; re-addresses all peers | | restart() | Bring the WireGuard interface down and then back up |

wg.admin.userConfig

| Method | Description | |---|---| | get() | Get defaults applied to newly created peers | | update(body) | Update defaults applied to newly created peers |

wg.admin.ipInfo

| Method | Description | |---|---| | get() | Get the server's public IP information (cached) |

wg.information - InformationAPI

Public endpoint; no authentication required.

| Method | Description | |---|---| | get() | Current/latest release, update availability, AWG mode, firewall status |

wg.setup - SetupAPI

First-run setup wizard endpoints. Only valid during the corresponding setup step.

| Method | Description | |---|---| | createAdmin(body) | Step 2 - Create the initial admin account | | getIpInfo() | Step 4 (GET) - Fetch public IP info to pre-fill host/port | | finalize({ host, port }) | Step 4 (POST) - Complete setup | | migrate({ file }) | Migrate a legacy wg-easy JSON backup to complete setup |

Advanced: raw Axios access

The underlying Axios instance is exposed if you need custom requests or interceptors:

wg.http.axios.interceptors.request.use((config) => {
  config.headers['X-Custom-Header'] = 'value';
  return config;
});

const res = await wg.http.axios.get('/api/some-endpoint');

Error Handling

All methods throw an AxiosError on non-2xx responses. The server's error description is in error.response.data.statusMessage.

import { isAxiosError } from 'axios';

try {
  await wg.session.login({ username: 'bad', password: 'wrongpassword', remember: false });
} catch (err) {
  if (isAxiosError(err)) {
    console.error(err.response?.status);                 // 401
    console.error(err.response?.data.statusMessage);     // "Invalid credentials"
  }
}

Project Structure

src/
├── types.ts          All request / response types and enums
├── http.ts           HttpClient (Axios wrapper)
├── WgEasyClient.ts   Main entry-point class
├── index.ts          Barrel exports
└── api/
    ├── session.ts
    ├── me.ts
    ├── clients.ts
    ├── admin.ts
    ├── information.ts
    └── setup.ts

This SDK was built with help from Claude Code by Anthropic. Types come from the wg-easy source.