@panoptic-it-solutions/unifi-api-client NPM

@panoptic-it-solutions/unifi-api-client

A modern, fully-typed Node.js client library for the UniFi Controller API.
Supports authentication (including 2FA), robust error handling, modular endpoints, and TypeScript-first development.

Installation

pnpm add @panoptic-it-solutions/unifi-api-client
# or
npm install @panoptic-it-solutions/unifi-api-client

Basic Usage

import { UniFiClient } from '@panoptic-it-solutions/unifi-api-client';

const client = new UniFiClient('https://unifi.example.com:8443', {
  username: 'admin',
  password: 'password',
  site: 'default', // optional, defaults to 'default'
  strictSSL: true, // optional, defaults to true
  timeout: 10000,  // optional, ms
  // logger: customLoggerInstance, // optional
});

await client.login(); // uses stored credentials

// Example: List all devices
const devices = await client.devices.listDevices();
console.log(devices);

await client.logout();

Authentication

Username/password authentication (2FA supported if enabled).
Session persistence with automatic re-authentication.
Emits authentication events for custom handling.

await client.login(); // uses credentials from constructor
// or
await client.login('admin', 'password'); // override credentials

Configuration Options

Option	Type	Default	Description
username	string	-	UniFi username
password	string	-	UniFi password
site	string	'default'	UniFi site name
strictSSL	boolean	true	Enforce SSL certificate validation
timeout	number	10000	Request timeout in milliseconds
logger	Logger or LoggerOptions	-	Custom logger instance or options

API Overview

Devices: List, adopt, restart, block/unblock, update firmware, etc.
Clients: List, block/unblock, authorize guests, get stats.
Sites: List, switch, get site info.
Networks: List, create, update, delete VLANs and networks.
WLANs: List, create, update, delete wireless networks.
Statistics: Retrieve usage, client, device, and site stats.
System: Get status, settings, logs, alerts, backups, firmware, reboot, factory reset.

Example: Device Management

// List all devices
const devices = await client.devices.listDevices();

// Get a device by MAC
const device = await client.devices.getDevice('aa:bb:cc:dd:ee:ff');

// Adopt a device
await client.devices.adoptDevice('aa:bb:cc:dd:ee:ff');

// Restart a device
await client.devices.restartDevice('aa:bb:cc:dd:ee:ff');

// Set device name
await client.devices.setDeviceName('aa:bb:cc:dd:ee:ff', 'My AP');

Example: Client Management

// List all active clients
const activeClients = await client.getActiveClients();

// Block a client
await client.blockClient('aa:bb:cc:dd:ee:ff');

// Authorize a guest client for 120 minutes
await client.authorizeGuest('aa:bb:cc:dd:ee:ff', 120);

Example: Network and Firewall

// List all networks
const networks = await client.getNetworks();

// Create a new network
const newNetwork = await client.createNetwork({
  name: 'IoT',
  vlan: 20,
  // ...other network options
});

// List all firewall rules
const rules = await client.getFirewallRules();

Error Handling

All methods throw custom error classes (UniFiApiError, UniFiAuthError, etc.).

try {
  await client.login();
  const clients = await client.getClients();
} catch (err) {
  if (err instanceof UniFiAuthError) {
    // Handle authentication error
  } else {
    // Handle other errors
  }
}