Important update for all UniFi API users: switch to local admin accounts before July 2024

Ubiquiti has recently announced a significant change to its authentication policies, particularly regarding the UniFi controller and UniFi OS consoles. Starting July 2024, all UniFi cloud accounts will be required to enable Multi-Factor Authentication (MFA) to enhance security measures.

If you have a Ubiquiti account and do not yet have MFA enabled, you will probably have received the following message by now:

Here's a link to Ubiquiti's announcement:

https://community.ui.com/questions/Upcoming-Multi-Factor-Authentication-MFA-Requirement-for-All-UI-Accounts-in-July-2024/e0d06d3c-c0ae-4af6-aa67-53c159d486a8

While we fully support Ubiquiti's efforts in bolstering security, this change directly impacts how software solutions integrate with the UniFi controller software through the API.

What does this mean for you?

To continue using your application that integrates with the UniFi platform, it is imperative to transition from using UniFi Cloud accounts for authentication, to local admin accounts on your UniFi controller as soon as possible. This shift is crucial because, unlike UniFi Cloud accounts, local admin accounts are not subject to the upcoming MFA requirement. To clarify; local accounts are basically administrator accounts that do not leverage UniFi Cloud.

Why switch to a local admin account?

• Uninterrupted API Integration: Ensures that the UniFi controller integration with your software keeps running smooth and without hitches.

• Simplified Access: Local admin accounts provide straightforward API access for integrated applications without the need for MFA. Also, using dedicated accounts for integrations is recommended over using personal accounts because it allows you to keep track of the account activity in the controller.

How to make the switch (for software-based controllers)

Log in to your software-based/self-hosted UniFi Controller using the new interface and follow the the steps below.

Create a local admin account:

• Navigate to the Settings section

• Select System, then click on the Administration tab

• Click on Add New Admin and make sure to disable the Remote Access checkbox

• Enter an email address, username, and set a password after selecting the Set Admin Password checkbox

• Make sure to take note of the username and password.

• Assign the necessary Site Permissions to the new account, ensuring it has the same level of access as your current UniFi cloud account. Generally, selecting the Site Administrator role will be required. For some types of applications (e.g. for reporting tools) the View Only role will be sufficient. Here's what the new local Admin account should look like:

• Click Invite to save the new Admin account.

• Log into the UniFi Controller using the new credentials, you will be asked to update the password. Take note of the updated password.

Log into your integrated software and update your integration settings with the username of the newly created local admin account and its updated password.

How to make the switch (for UniFi OS consoles)

For UniFi OS consoles, a local admin account is created as follows.

• Open the UniFi OS home page on the device

• Select Admins > Add Admin (using the + icon)

• Create an Admin account similar to this example:

Log into your integrated software and update your integration settings with the username of the newly created local admin account and its updated password.

Act now

We urge you not to wait until the last minute to make this transition. Early action will prevent any potential disruption to your services and give you ample time to adjust to the new setup.

We're here to help

We understand that changes like these can be challenging, but our team is here to ensure that this transition is as smooth as possible for our clients. If you have any concerns or need assistance, please do not hesitate to reach out to us.