Use a Local Admin Account for UniFi API & Captive Portal Integrations (Avoid MFA)

If your Art of WiFi Captive Portal, reporting scripts, or other UniFi integrations suddenly started throwing errors after Ubiquiti's MFA rollout, you're not alone. Beginning July 22, 2024, Ubiquiti requires Multi‑Factor Authentication (MFA) for UI.com (cloud) accounts. Automated services and applications that attempt to log in with those cloud credentials get stalled at the second factor prompt and effectively lose API access. The original fix was to create a dedicated local admin (service) account on your UniFi console and use that for all programmatic API connections. Local accounts are not subject to the cloud MFA requirement and continue to authenticate cleanly.

🆕 Our captive portal solutions and the UniFi Device Search Tool now support two additional authentication options: a Network Application API Key (for direct connections) and a Site Manager API Key (for connections via unifi.ui.com). More Art of WiFi products will follow soon. Read our companion guide to understand the differences and choose the best method for your setup:

👉 UniFi API Authentication: Local Admin vs. API Key vs. Site Manager

Who should read this?

You should take action if you use any external tool that signs into the UniFi Network Application / controller on your behalf, including:

• Art of WiFi Captive Portal & reporting tools

• Other 3rd party, external, captive portal solutions

• Home/business automation platforms (Home Assistant, etc.)

• Custom scripts built on our UniFi‑API‑client library

• Monitoring, billing, or MSP dashboards that poll UniFi stats

All of these rely on unattended logins through the API; MFA breaks unattended logins when using UI.com credentials. Community reports confirm breakage and successful resolution by switching to a local admin account.

Quick TL;DR

Create a dedicated local admin account (service account). Disable Remote/Cloud access for it. Grant the minimum role required (often Site Admin or View Only). Update your integration to use that username/password.‘ That’s it.’

‘Or,’‘ if you prefer keyless authentication or need to connect through unifi.ui.com, see our ‘‘full comparison of all three authentication methods’.

Why cloud logins with MFA break API integrations

UI.com accounts now require MFA; even if you don't enable an app‑based factor proactively, email verification is auto‑enabled after the enforcement date. Programmatic tools cannot satisfy an interactive second factor, so authentication fails or loops. Partners in the UniFi ecosystem (captive portal vendors, monitoring tools, automation frameworks) flagged this in advance because their products would lose access without a non‑MFA login path. Local admin accounts remain exempt, which is why nearly every vendor (including us) recommends moving integrations to a local account.

Common symptoms

• Repeated MFA / verification prompts to the account owner’s email or authenticator app.

• API calls returning 401 Unauthorized in logs.

• External applications such as captive portals fail to connect. These patterns were widely reported in community forums when MFA enforcement began.

Local admin vs. UI.com (cloud) account: what's the difference?

UI.com (cloud) account: Centralized identity hosted by Ubiquiti; used for remote management and marketplace services. Subject to mandatory MFA.
Local admin account: Lives only on the UniFi console/Network Application you create it on. Can be scoped to specific sites and roles. Operates in local‑only mode with no cloud linkage; MFA not imposed. Official UniFi documentation distinguishes between remote cloud admins and local‑only management and shows where to add them in the Network Application UI.

What level of access does the service account need?

Most captive portal and reporting integrations need read/write access to the API — Site Admin is typically sufficient. For pure reporting (read‑only stats pulls) you can grant View Only to reduce risk. UniFi’s role matrix (Full Management, Site Admin, View Only, Hotspot Operator, etc.) lets you scope the least privileges required. Our older advisory showed Site Admin as the safe default; choose tighter roles if your workflow allows.

Step‑by‑Step: Create a Local Admin Account

Good practice: Name the account something service‑oriented (e.g., aow-cp-svc), do not reuse a personal email, and store the password in a secure vault.

Before you start

• Confirm which UniFi platform you’re on (UniFi OS console such as UDM, UCG, UX, etc. vs. self‑hosted software install).

• Confirm your running version; menu names changed between Network Application 7.x, 8.x, 9.x, and 10.x.

• Decide the role and which sites the account should see.

A. UniFi OS Consoles (UDM, UCK, UX, etc.)

• Log in to the UniFi OS Console web UI with an existing admin.

• Go to Admins & Users (label may read Admins in some versions).

• Create New User( + ).

• Check the Admin checkbox.

• Restrict to local access only / Disable Remote Access so the account is local (wording varies by version).

• Username & Password: Enter a username (doesn’t need to be an email) and set a strong password.

• Role / Permissions: Uncheck Use pre‑defined role if present; assign Site Admin (or minimum required) for the Network Application. Select None for other sections where no permissions are needed.

• Create.

• Test login locally at https://<console-ip>/ using the new credentials.

B. Self‑Hosted Software install

• Sign in to the Controller/Network Application.

• Navigate to Admins.

• Select Current Site if you wish to restrict the Local Admin account to the current site.

• Click on plus icon (+) to add a new admin.

• Uncheck Remote Access (ensures local‑only).

• Select Set Admin Password (check the box if required) and enter the username and password.

• Assign Role: Choose Site Administrator (or View Only for read‑only/reporting).

• Invite / Save, then log out and back in with the new local credentials to finalize.

These steps mirror the guidance we published in 2024 and remain valid; wording may vary in 8.x/9.x/10.x UI but the flow is unchanged.

‘Update Your Integration’

‘Art of WiFi Captive Portal & Tools’

Open your portal’s or tool’s ‘UniFi connection settings’‘ and replace the stored credentials with one of the supported authentication methods:’

• ‘Local admin username/password’‘ (covered in this article). The classic approach, works with all console types including the legacy self-hosted Network Application.’

• ‘Network Application API Key’‘. Requires the latest release of your Art of WiFi product and a direct connection to a UniFi OS console or Server. No username/password needed.’

• ‘Site Manager API Key’‘. Requires the latest release of your Art of WiFi product; connects through unifi.ui.com, ideal when your console has a dynamic IP, is behind CGNAT, or is otherwise not directly reachable. UniFi OS console or Server only.’

‘For a detailed comparison of when to use each method, see our ‘‘companion guide’.

‘If you connect over WAN using the local admin method, ensure firewall rules permit HTTPS (port 443 on UniFi OS consoles, port 11443 on UniFi OS Server, or 8443 on older software controllers) from your portal host to the console.’

Authentication methods the Art of WiFi captive portal can offer (beyond email capture)

Even though this article is about API credentials, it’s a good moment to revisit guest authentication options you can add to your UniFi guest network with the Art of WiFi captive portal:

• Email registration & verification (great for marketing follow‑up).

• SMS / mobile phone verification with one‑time passwords (OTP).

• Azure Entra ID / Microsoft 365 (OAuth2) single sign‑on for students/staff.

• Social logins (Facebook, Instagram) and sponsored access approval flows.

Security Best Practices for Local Admin Accounts

Related

👉 UniFi API Authentication: Local Admin vs. API Key vs. Site Manager

👉 Captive Portal Software for UniFi Networks