Class ClientManagementAPI

Block a client device

Blocks network access for a specific client device by MAC address. The device will be unable to connect to the network until unblocked.

Throws

When MAC address validation fails

Throws

When client blocking fails

Example

// Block a client device
await clientAPI.block_sta('default', 'aa:bb:cc:dd:ee:ff');

// Block with cancellation support
const controller = new AbortController();
await clientAPI.block_sta('default', 'aa:bb:cc:dd:ee:ff', { signal: controller.signal });
Copy

See

• unblock_sta to unblock a client device
• list_users to get client device information

PHP: block_sta($mac) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/stamgr', $payload);

Create hotspot operator

Creates a new hotspot operator account for managing guest access. Hotspot operators can create and manage vouchers for guest network access.

Throws

When name or password is invalid

Throws

When hotspot operator creation fails

Example

// Create basic hotspot operator
await clientAPI.create_hotspotop('reception', 'securepassword123');

// Create hotspot operator with note
await clientAPI.create_hotspotop(
  'conference_desk',
  'conf2024!',
  'Conference registration desk operator'
);
Copy

See

• list_hotspotop to view existing operators
• create_voucher for voucher creation by operators

PHP: create_hotspotop($name, $x_password, $note = '')

List hotspot operators

Retrieves a list of all hotspot operators configured in the UniFi Controller. Hotspot operators can manage guest access and create vouchers.

Throws

When hotspot operator listing fails

Example

// Get all hotspot operators
const operators = await clientAPI.list_hotspotop();
console.log(`Found ${operators.length} hotspot operators`);

// Find specific operator
const receptionOp = operators.find(op => op.name === 'reception');
if (receptionOp) {
  console.log(`Reception operator note: ${receptionOp.note}`);
}
Copy

See

create_hotspotop to create new operators

PHP: list_hotspotop() -> return $this->fetch_results('/api/s/' . $this->site . '/list/hotspotop');

List all client devices (users/stations) connected to the UniFi network

Description

Retrieves a list of all client devices that have connected to the UniFi network. This includes both currently connected and previously connected devices.

Example

// Get all clients
const clients = await clientAPI.list_users();
console.log(`Found ${clients.length} clients`);

// With request cancellation
const controller = new AbortController();
const clients = await clientAPI.list_users('default', { signal: controller.signal });
Copy

See

• list_active_clients for only currently connected clients
• list_clients_history for historical client data

Since

1.0.0

Remarks

PHP: list_users() -> return $this->fetch_results('/api/s/' . $this->site . '/list/user');

Authorize a guest client device for network access

Description

Grants network access to a guest device for a specified duration with optional bandwidth and data limits. The device will be automatically unauthorized after the time expires.

Throws

When MAC address format is invalid

Throws

When device is already authorized or authorization fails

Example

// Basic guest authorization for 60 minutes
await clientAPI.authorize_guest('default', 'aa:bb:cc:dd:ee:ff', 60);

// With bandwidth limits (5 Mbps up, 10 Mbps down)
await clientAPI.authorize_guest('default', 'aa:bb:cc:dd:ee:ff', 120, 5000, 10000);

// With data limit (1 GB)
await clientAPI.authorize_guest('default', 'aa:bb:cc:dd:ee:ff', 180, undefined, undefined, 1024);

// Restrict to specific Access Point
await clientAPI.authorize_guest(
  'default',
  'aa:bb:cc:dd:ee:ff', 
  240, 
  2000, 
  5000, 
  512, 
  '11:22:33:44:55:66'
);
Copy

See

• unauthorize_guest to revoke guest access
• extend_guest_validity to extend guest session
• list_guests to view current guest sessions

Since

1.0.0

Remarks

PHP: authorize_guest($mac, $minutes, $up = null, $down = null, $megabytes = null, $ap_mac = null)

List active client devices PHP: list_active_clients($include_traffic_usage = true, $include_unifi_devices = true)

List client devices PHP: list_clients($mac = '') -> return $this->fetch_results('/api/s/' . $this->site . '/stat/sta', $payload);

List client history PHP: list_clients_history($historyhours = 8760, $start = null, $end = null, $mac = null) -> return $this->fetch_results('/api/s/' . $this->site . '/stat/sta', $payload);

Fetch details for a single client device PHP: stat_client($mac) -> return $this->fetch_results('/api/s/' . $this->site . '/stat/user/' . strtolower(trim($mac)));

Unblock a station PHP: unblock_sta($mac) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/stamgr', $payload);

Reconnect client device (kick and reconnect) PHP: reconnect_sta($mac) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/stamgr', $payload);

Forget client device PHP: forget_sta($mac) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/stamgr', $payload);

Edit client fixed IP PHP: edit_client_fixedip($client_id, $use_fixedip, $network_id = null, $fixed_ip = null)

Edit client name PHP: edit_client_name($client_id, $name)

Set client device name PHP: set_sta_name($user_id, $name = '') -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/upd/user/' . trim($user_id), $payload);

Set client device note PHP: set_sta_note($user_id, $note = '') -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/upd/user/' . trim($user_id), $payload);

Unauthorize a guest PHP: unauthorize_guest($mac) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/stamgr', $payload);

Extend guest validity PHP: extend_guest_validity($guest_id) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/hotspot', $payload);

List guest devices PHP: list_guests($within = 8760) -> return $this->fetch_results('/api/s/' . $this->site . '/stat/guest', $payload);

Fetch sessions PHP: stat_sessions($start = null, $end = null, $mac = null, $type = 'all') -> return $this->fetch_results('/api/s/' . $this->site . '/stat/session', $payload);

Fetch latest sessions for a station PHP: stat_sta_sessions_latest($mac, $limit = null) -> return $this->fetch_results('/api/s/' . $this->site . '/stat/session', $payload);

Create tag

Creates a new tag for organizing and managing client devices. Tags can be used to group devices for easier management and policy application.

Throws

When name is invalid

Throws

When tag creation fails

Example

// Create empty tag
await clientAPI.create_tag('VIP Devices');

// Create tag with initial devices
await clientAPI.create_tag('Conference Room', [
  'aa:bb:cc:dd:ee:ff',
  'ff:ee:dd:cc:bb:aa'
]);
Copy

See

• list_tags to view existing tags
• set_tagged_devices to modify tag membership
• delete_tag to remove tags

PHP: create_tag($name, $macs = null)

Delete tag

Permanently deletes a tag from the UniFi Controller. This removes the tag and all device associations.

Throws

When tag_id is invalid

Throws

When tag deletion fails

Example

// Delete tag by ID
await clientAPI.delete_tag('507f1f77bcf86cd799439011');

// Find and delete tag by name
const tags = await clientAPI.list_tags();
const oldTag = tags.find(tag => tag.name === 'Old Devices');
if (oldTag) {
  await clientAPI.delete_tag(oldTag._id);
}
Copy

Warning

This operation removes all device associations with the tag

See

• list_tags to get tag IDs
• create_tag to create new tags

PHP: delete_tag($tag_id) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/tag/' . $tag_id);

Get tag

Retrieves detailed information about a specific tag including its member devices.

Throws

When tag_id is invalid

Throws

When tag retrieval fails

Example

// Get specific tag details
const tag = await clientAPI.get_tag('507f1f77bcf86cd799439011');
console.log(`Tag "${tag.name}" has ${tag.member_table?.length || 0} devices`);

// Check if device is in tag
const deviceMac = 'aa:bb:cc:dd:ee:ff';
const isTagged = tag.member_table?.includes(deviceMac.toLowerCase());
Copy

See

• list_tags to get all tags
• set_tagged_devices to modify tag membership

PHP: get_tag($tag_id) -> return $this->fetch_results('/api/s/' . $this->site . '/rest/tag/' . $tag_id);

List tags

Retrieves a list of all tags configured in the UniFi Controller. Tags are used for organizing and managing client devices.

Throws

When tag listing fails

Example

// Get all tags
const tags = await clientAPI.list_tags();
console.log(`Found ${tags.length} tags`);

// Find tags with devices
const activeTags = tags.filter(tag => 
  tag.member_table && tag.member_table.length > 0
);

// Get tag names
const tagNames = tags.map(tag => tag.name);
Copy

See

• create_tag to create new tags
• get_tag to get detailed tag information
• delete_tag to remove tags

PHP: list_tags() -> return $this->fetch_results('/api/s/' . $this->site . '/list/tag');

Set tagged devices

Updates the list of devices associated with a specific tag. This replaces the current device list with the provided MAC addresses.

Throws

When tag_id or device_macs is invalid

Throws

When tag device assignment fails

Example

// Assign devices to tag
await clientAPI.set_tagged_devices('507f1f77bcf86cd799439011', [
  'aa:bb:cc:dd:ee:ff',
  'ff:ee:dd:cc:bb:aa',
  '11:22:33:44:55:66'
]);

// Clear all devices from tag
await clientAPI.set_tagged_devices('507f1f77bcf86cd799439011', []);

// Add single device to tag (replacing all others)
await clientAPI.set_tagged_devices('507f1f77bcf86cd799439011', [
  'aa:bb:cc:dd:ee:ff'
]);
Copy

Warning

This replaces the entire device list - existing devices not in the array will be removed

See

• get_tag to see current device assignments
• list_tags to get tag IDs

PHP: set_tagged_devices($tag_id, $device_macs) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/tag/' . $tag_id, $payload);

Create voucher

Creates guest access vouchers with specified duration, bandwidth limits, and usage quotas. Vouchers provide temporary network access without requiring device registration.

Throws

When parameters are invalid

Throws

When voucher creation fails

Example

// Create single voucher for 60 minutes
const voucher = await clientAPI.create_voucher(60);

// Create 10 vouchers with bandwidth limits (5 Mbps down, 2 Mbps up)
await clientAPI.create_voucher(
  120,    // 2 hours
  10,     // 10 vouchers
  0,      // unlimited usage
  'Conference guests',
  2000,   // 2 Mbps up
  5000    // 5 Mbps down
);

// Create voucher with data limit (500 MB)
await clientAPI.create_voucher(
  180,    // 3 hours
  1,      // 1 voucher
  0,      // unlimited usage
  'Limited data access',
  undefined, // no upload limit
  undefined, // no download limit
  500     // 500 MB data limit
);
Copy

See

• revoke_voucher to revoke vouchers
• list_guests to see active voucher sessions

PHP: create_voucher($minutes, $count = 1, $quota = 0, $note = '', $up = null, $down = null, $megabytes = null)

Revoke voucher

Revokes (deletes) a specific voucher, making it invalid for future use. This does not affect currently active sessions using the voucher.

Throws

When voucher_id is invalid

Throws

When voucher revocation fails

Example

// Revoke specific voucher
await clientAPI.revoke_voucher('507f1f77bcf86cd799439011');

// Find and revoke vouchers by note
const vouchers = await clientAPI.stat_voucher();
const conferenceVouchers = vouchers.filter(v => 
  v.note && v.note.includes('Conference')
);
for (const voucher of conferenceVouchers) {
  await clientAPI.revoke_voucher(voucher._id);
}
Copy

Warning

This permanently deletes the voucher - it cannot be recovered

See

• create_voucher to create new vouchers
• stat_voucher to list existing vouchers

PHP: revoke_voucher($voucher_id) -> return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/hotspot', $payload);