Class UniFiClient

Creates a new UniFi API client instance

Throws

When required configuration parameters are missing or invalid

Example

const client = new UniFiClient({
  baseUrl: 'https://192.168.1.1:8443',
  username: 'admin',
  password: 'mypassword',
  site: 'default',
  timeout: 10000,
  verifySsl: false
});
Copy

Authenticates with the UniFi controller

Establishes a session with the UniFi controller using the provided credentials. This method must be called before making any API requests that require authentication.

Throws

When login credentials are invalid

Throws

When unable to connect to the controller

Throws

When client configuration is invalid

Example

try {
  await client.login();
  console.log('Successfully logged in');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid credentials');
  } else {
    console.error('Login failed:', error.message);
  }
}
Copy

Logs out from the UniFi controller

Terminates the current session with the UniFi controller and clears all authentication cookies. This method should be called when finished with the client.

Example

// Always logout when done
try {
  await client.logout();
  console.log('Successfully logged out');
} catch (error) {
  console.warn('Logout failed, but session cleared locally');
}
Copy

Checks if the client is currently authenticated

Returns the current authentication status without making any network requests. Note that this only reflects the local session state and doesn't verify if the session is still valid on the server.

Example

if (!client.isAuthenticated()) {
  await client.login();
}

// Now safe to make API calls
const devices = await client.listDevices();
Copy

Retrieves current session information

Returns detailed information about the current session including authentication status, login time, last activity, and user details.

Example

const sessionInfo = client.getSessionInfo();
console.log(`Logged in as: ${sessionInfo.username}`);
console.log(`Site: ${sessionInfo.site}`);
console.log(`Session active: ${sessionInfo.isAuthenticated}`);
Copy

Gets the configured site name

Returns the site name that this client instance is configured to work with. All API operations will be performed in the context of this site.

Example

const site = client.getSite();
console.log(`Working with site: ${site}`);
Copy

Gets the underlying HTTP client instance

Provides access to the internal HTTP client for advanced usage scenarios such as custom request configuration or direct API calls.

Example

const httpClient = client.getHttpClient();

// Make a custom API call
const response = await httpClient.get('/api/s/default/stat/health');
Copy

Gets the authentication API instance

Provides access to the authentication API for advanced authentication scenarios such as custom authentication flows or session monitoring.

Example

const authAPI = client.getAuthenticationAPI();

// Check if session needs refresh
await authAPI.ensureAuthenticated();
Copy

Gets the session manager instance

Provides access to the internal session manager for advanced session management scenarios such as custom authentication flows or session monitoring.

Example

const sessionManager = client.getSessionManager();

// Check if session needs refresh
await sessionManager.ensureAuthenticated();
Copy

Gets the device management API instance

Provides access to the device management API for advanced device management scenarios such as custom device operations or bulk operations.

Example

const deviceAPI = client.getDeviceManagementAPI();

// Use device management API directly
const devices = await deviceAPI.list_devices();
Copy

Gets the client management API instance

Provides access to the client management API for advanced client management scenarios such as bulk client operations or guest management.

Example

const clientAPI = client.getClientManagementAPI();

// Use client management API directly
const clients = await clientAPI.list_users();
await clientAPI.block_sta('default', 'aa:bb:cc:dd:ee:ff');
Copy

Get the Network Management API instance

Provides access to network configuration operations including network creation, VLAN management, routing configuration, DNS settings, and port forwarding.

Example

const networkAPI = client.getNetworkManagementAPI();

// Use network management API directly
const networks = await networkAPI.list_networkconf();
await networkAPI.create_network({
  name: 'Guest Network',
  purpose: 'guest',
  ip_subnet: '192.168.100.1/24'
});
Copy

Get the Site Management API instance

Provides access to site management operations including site creation, deletion, configuration, and statistics.

Example

const siteAPI = client.getSiteManagementAPI();

// Use site management API directly
const sites = await siteAPI.list_sites();
await siteAPI.create_site('New Branch Office');
await siteAPI.set_site_name('Updated Office Name');
const stats = await siteAPI.stat_sites();
Copy

Get the User Management API instance

Provides access to user, user group, and administrator management operations including user creation, group management, and admin permissions.

Example

const userAPI = client.getUserManagementAPI();

// Use user management API directly
const users = await userAPI.list_users();
await userAPI.create_user('aa:bb:cc:dd:ee:ff', 'group_id', 'John Doe');
const groups = await userAPI.list_usergroups();
Copy

Get the Security API instance

Provides access to security-related operations including firewall management, IPS/IDS settings, RADIUS authentication, and access controls.

Example

const securityAPI = client.getSecurityAPI();

// Use security API directly
const firewallGroups = await securityAPI.list_firewallgroups();
await securityAPI.create_firewallgroup('BlockedIPs', 'address-group', ['192.168.1.100']);
const radiusAccounts = await securityAPI.list_radius_accounts();
Copy

Get the Statistics API instance

Provides access to statistics and monitoring operations including system health, event monitoring, and various time-based statistics.

Example

const statsAPI = client.getStatisticsAPI();

// Use statistics API directly
const sysInfo = await statsAPI.stat_sysinfo();
const events = await statsAPI.list_events();
const health = await statsAPI.list_health();
Copy