Class UserManagementAPI

Create a new user (client device) in the UniFi network

Description

Creates a new user entry for a client device with specified MAC address and assigns it to a user group. This allows for bandwidth control and access policies to be applied to the device.

Throws

When MAC address or user_group_id validation fails

Throws

When user creation fails

Example

// Create basic user
const user = await userMgmt.create_user(
  'default',
  'aa:bb:cc:dd:ee:ff',
  'default-usergroup'
);

// Create user with full details
await userMgmt.create_user(
  'default',
  'aa:bb:cc:dd:ee:ff',
  'guest-usergroup',
  'John Doe',
  'Conference guest',
  true,  // is_guest
  false  // is_wired
);

// Create wired user
await userMgmt.create_user(
  'default',
  'aa:bb:cc:dd:ee:ff',
  'corporate-usergroup',
  'Office Workstation',
  'Marketing department PC',
  false, // is_guest
  true   // is_wired
);
Copy

See

• list_usergroups to get available user groups
• set_usergroup to modify user group membership

Since

1.0.0

Remarks

PHP: create_user($mac, $user_group_id, $name = null, $note = null, $is_guest = null, $is_wired = null)

Set user group for a client device

Description

Assigns a client device to a specific user group, which controls bandwidth limits and access policies for that device.

Throws

When client_id or group_id validation fails

Throws

When user group assignment fails

Example

// Assign user to VIP group
await userMgmt.set_usergroup('default', 'user123', 'vip-group-id');

// Move guest to limited bandwidth group
await userMgmt.set_usergroup('default', 'guest456', 'guest-group-id');
Copy

See

• list_usergroups to get available user groups
• create_user to create new users

Since

1.0.0

Remarks

PHP: set_usergroup($client_id, $group_id)

Create user group

Description

Creates a new user group with specified bandwidth limits. User groups control download/upload speeds and access policies for client devices.

Throws

When group_name validation fails

Throws

When user group creation fails

Example

// Create unlimited bandwidth group
const group = await userMgmt.create_usergroup('default', 'VIP Users');

// Create group with bandwidth limits (10 Mbps down, 5 Mbps up)
await userMgmt.create_usergroup('default', 'Guest Users', 10000, 5000);

// Create group with download limit only
await userMgmt.create_usergroup('default', 'Basic Users', 5000, -1);
Copy

See

• list_usergroups to list existing user groups
• delete_usergroup to remove a user group

Since

1.0.0

Remarks

PHP: create_usergroup($group_name, $group_dn = -1, $group_up = -1)

List user groups

Description

Retrieves all user groups configured in the site. User groups define bandwidth limits and access policies for client devices.

Throws

When user group list retrieval fails

Example

// Get all user groups
const groups = await userMgmt.list_usergroups('default');
console.log(`Found ${groups.length} user groups`);

// Find specific group by name
const vipGroup = groups.find(group => group.name === 'VIP Users');
if (vipGroup) {
  console.log(`VIP group ID: ${vipGroup._id}`);
}
Copy

See

• create_usergroup to create new user groups
• delete_usergroup to remove user groups

Since

1.0.0

Remarks

PHP: list_usergroups()

Delete user group

Description

Removes a user group from the site. Users assigned to the deleted group will be moved to the default user group.

Throws

When group_id is invalid

Throws

When user group deletion fails

Example

// Delete user group by ID
await userMgmt.delete_usergroup('default', '507f1f77bcf86cd799439011');

// Find and delete user group by name
const groups = await userMgmt.list_usergroups('default');
const guestGroup = groups.find(group => group.name === 'Guest Users');
if (guestGroup) {
  await userMgmt.delete_usergroup('default', guestGroup._id);
}
Copy

Warning

Users in the deleted group will be moved to the default group

See

• list_usergroups to get user group IDs
• create_usergroup to create a new user group

Since

1.0.0

Remarks

PHP: delete_usergroup($group_id)

Edit user group

Description

Updates an existing user group's configuration including name and bandwidth limits. This allows modification of download/upload speed limits and group identification.

Throws

When group_id, site_id, or group_name validation fails

Throws

When user group update fails

Example

// Update group name only
await userMgmt.edit_usergroup(
  'default',
  'group123',
  'site456',
  'Updated VIP Users'
);

// Update group with new bandwidth limits (20 Mbps down, 10 Mbps up)
await userMgmt.edit_usergroup(
  'default',
  'group123',
  'site456',
  'High Speed Users',
  20000,  // 20 Mbps down
  10000   // 10 Mbps up
);

// Remove bandwidth limits (set to unlimited)
await userMgmt.edit_usergroup(
  'default',
  'group123',
  'site456',
  'Unlimited Users',
  -1,     // unlimited down
  -1      // unlimited up
);
Copy

See

• list_usergroups to get user group IDs
• create_usergroup to create new user groups

Since

1.0.0

Remarks

PHP: edit_usergroup($group_id, $site_id, $group_name, $group_dn = -1, $group_up = -1)

List site administrators

Description

Retrieves a list of administrators who have access to the current site. Includes information about admin roles and permissions.

Throws

When administrator list retrieval fails

Example

// Get all site administrators
const admins = await userMgmt.list_admins('default');
console.log(`Site has ${admins.length} administrators`);

// Find super administrators
const superAdmins = admins.filter(admin => admin.role === 'admin');

// List admin emails
const adminEmails = admins.map(admin => admin.email);
console.log('Admin emails:', adminEmails);
Copy

See

• invite_admin to invite new administrators
• revoke_admin to remove administrator access

Since

1.0.0

Remarks

PHP: list_admins()

List all administrators across all sites

Description

Retrieves a comprehensive list of all administrators across all sites in the UniFi Controller. This is useful for global administrator management.

Throws

When administrator list retrieval fails

Example

// Get all administrators across all sites
const allAdmins = await userMgmt.list_all_admins();
console.log(`Total administrators: ${allAdmins.length}`);

// Find administrators by email domain
const companyAdmins = allAdmins.filter(admin => 
  admin.email.endsWith('@company.com')
);
Copy

See

list_admins to get administrators for a specific site

Since

1.0.0

Remarks

PHP: list_all_admins()

Invite admin user

Description

Invites a new administrator to the site with specified permissions. The invited user will receive an email invitation to access the UniFi Controller.

Throws

When email validation fails

Throws

When admin invitation fails

Example

// Invite basic administrator
await userMgmt.invite_admin(
  'default',
  'John Smith',
  'john.smith@company.com'
);

// Invite read-only administrator
await userMgmt.invite_admin(
  'default',
  'Jane Doe',
  'jane.doe@company.com',
  true,  // enable_sso
  true   // readonly
);

// Invite administrator with device permissions
await userMgmt.invite_admin(
  'default',
  'Tech Lead',
  'tech@company.com',
  true,  // enable_sso
  false, // readonly
  true,  // device_adopt
  true   // device_restart
);
Copy

See

• list_admins to view current administrators
• revoke_admin to remove administrator access

Since

1.0.0

Remarks

PHP: invite_admin($name, $email, $enable_sso = true, $readonly = false, $device_adopt = false, $device_restart = false)

Assign an existing admin to a site

Description

Grants an existing administrator access to a specific site with configurable permissions and roles.

Throws

When admin_id validation fails

Throws

When admin assignment fails

Example

// Assign existing admin with full permissions
await userMgmt.assign_existing_admin('default', 'admin123');

// Assign with read-only access
await userMgmt.assign_existing_admin('default', 'admin456', true);

// Assign with device management permissions
await userMgmt.assign_existing_admin(
  'default',
  'admin789',
  false, // readonly
  true,  // device_adopt
  true   // device_restart
);
Copy

See

• list_all_admins to get existing administrator IDs
• revoke_admin to remove site access

Since

1.0.0

Remarks

PHP: assign_existing_admin($admin_id, $readonly = false, $device_adopt = false, $device_restart = false)

Update an admin

Description

Updates an existing administrator's information, permissions, and role. Can modify name, email, password, and various permission settings.

Throws

When email validation fails

Throws

When admin update fails

Example

// Update admin name and email
await userMgmt.update_admin(
  'default',
  'admin123',
  'John Smith Jr.',
  'john.smith.jr@company.com'
);

// Update admin with new password and permissions
await userMgmt.update_admin(
  'default',
  'admin456',
  'Jane Doe',
  'jane.doe@company.com',
  'newSecurePassword123',
  false, // readonly
  true,  // device_adopt
  true   // device_restart
);

// Promote to super administrator
await userMgmt.update_admin(
  'default',
  'admin789',
  'Super Admin',
  'super@company.com',
  '',    // keep current password
  false, // readonly
  false, // device_adopt
  false, // device_restart
  true   // is_super
);
Copy

See

• list_admins to get administrator information
• invite_admin to create new administrators

Since

1.0.0

Remarks

PHP: update_admin($admin_id, $name, $email, $password = '', $readonly = false, $device_adopt = false, $device_restart = false, $is_super = null)

Revoke admin privileges

Description

Removes administrator access from a user for the current site. The user will no longer be able to access or manage the site.

Throws

When admin_id validation fails

Throws

When admin revocation fails

Example

// Revoke admin access
await userMgmt.revoke_admin('default', 'admin123');

// Find and revoke admin by email
const admins = await userMgmt.list_admins('default');
const targetAdmin = admins.find(admin => admin.email === 'former@company.com');
if (targetAdmin) {
  await userMgmt.revoke_admin('default', targetAdmin._id);
}
Copy

Warning

This action cannot be undone. The user must be re-invited to regain access.

See

• list_admins to get administrator IDs
• invite_admin to re-invite administrators

Since

1.0.0

Remarks

PHP: revoke_admin($admin_id)

Grant super admin privileges

Description

Grants super administrator privileges to an existing administrator. Super administrators have elevated permissions across the entire UniFi Controller.

Throws

When admin_id validation fails

Throws

When super admin promotion fails

Example

// Grant super admin privileges
await userMgmt.grant_super_admin('default', 'admin123');

// Find and promote admin by name
const admins = await userMgmt.list_admins('default');
const targetAdmin = admins.find(admin => admin.name === 'Senior Admin');
if (targetAdmin) {
  await userMgmt.grant_super_admin('default', targetAdmin._id);
}
Copy

Warning

Super admin privileges provide extensive system access. Use carefully.

See

• list_admins to get administrator information
• update_admin for more granular permission control

Since

1.0.0

Remarks

PHP: grant_super_admin($admin_id)

Delete admin

Description

Removes an administrator from the site by revoking their super admin privileges. This is equivalent to calling revoke_admin but uses the delete-admin command.

Throws

When admin_id validation fails

Throws

When admin deletion fails

Example

// Delete admin by ID
await userMgmt.delete_admin('default', 'admin123');

// Find and delete admin by email
const admins = await userMgmt.list_admins('default');
const targetAdmin = admins.find(admin => admin.email === 'former@company.com');
if (targetAdmin) {
  await userMgmt.delete_admin('default', targetAdmin._id);
}
Copy

Warning

This action cannot be undone. The user must be re-invited to regain access.

See

• list_admins to get administrator IDs
• revoke_admin for alternative admin removal method

Since

1.0.0

Remarks

PHP: delete_admin($admin_id)