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

Our captive portal solutions and the UniFi Device Search Tool now support three ways to connect to the UniFi Network Application API. In addition to the familiar local admin credentials, you can now authenticate with a Network Application API Key or connect through unifi.ui.com using a Site Manager API Key. More Art of WiFi products will follow soon.

This guide explains how each method works, when to use it, and what trade-offs to consider. If you're already using a local admin account and everything works, there's no urgency to switch. But if you're dealing with CGNAT, dynamic IPs, or want to simplify credential management, read on.

Quick comparison

Rule of thumb: If you have a stable direct connection to the console, use an API Key or local admin. If you don't, use Site Manager.

Background: why three methods?

Historically, the UniFi Network Application only supported username/password authentication via its "classic" (unofficial) API. When Ubiquiti enforced MFA on cloud (UI.com) accounts in July 2024, automated integrations broke. The community-wide fix was switching to local admin accounts, which remain exempt from MFA.

Since then, Ubiquiti has introduced an official API with token-based authentication via API keys, both at the Network Application level and through the Site Manager at unifi.ui.com. We have built support for all three authentication methods into our products, giving you the flexibility to choose the connection method that best fits your network setup.

Method 1: Local Admin Credentials (username and password)

How it works

You create a dedicated local-only admin account on the UniFi console and authenticate using its username and password. Your Art of WiFi product opens a session via the classic (unofficial) API endpoints. This is the only method that works with all console types, including the legacy self-hosted Network Application.

Requirements

• Direct network connectivity between your integration host and the UniFi console (port 443 for UniFi OS consoles, 8443 for self-hosted controllers, 11443 for UniFi OS Server).

• A local admin account with Remote/Cloud access disabled.

• Appropriate role (typically Site Admin; View Only for read-only use cases).

Advantages

• Works with all versions of our products, including older releases.

• Well-understood, widely documented, battle-tested across thousands of deployments.

• Full access to the extensive classic API endpoint library.

• No dependency on Ubiquiti's cloud infrastructure.

Disadvantages

• Requires password management and periodic rotation.

• Needs direct connectivity. Doesn't work if the console is behind CGNAT or has a dynamic WAN IP without DDNS.

• Requires firewall rules when connecting over WAN.

When to use

This is the safe default, especially for existing deployments that already have it working. If your integration host can reach the console directly and you're comfortable managing a service account, there's little reason to change.

Setup

See our detailed step-by-step guide: Use a Local Admin Account for UniFi API & Captive Portal Integrations.

Method 2: Network Application API Key (direct connection)

How it works

Instead of a username and password, you generate an API key within the UniFi Network Application. Your Art of WiFi product authenticates using this key in request headers. No session or cookie management needed.

Requirements

• Latest version of your Art of WiFi captive portal or UniFi Device Search Tool (other products will be updated soon).

• Direct network connectivity to the console (same ports as local admin: 443 / 8443 / 11443).

• An API key generated from the Network Application's settings.

• A UniFi OS console or UniFi OS Server. The legacy self-hosted Network Application does not support API key authentication.

How to create an API key

1. Log into your UniFi Network Application.

2. Navigate to Settings → Control Plane → API Access (wording may vary by version).

3. Create a new API key. Give it a descriptive name (e.g., aow-captive-portal).

4. Copy the key immediately. It won't be shown again.

5. Store it securely (password manager or secrets vault).

Note: The exact menu location may differ between Network Application versions 8.x, 9.x, and 10.x. Look for API-related settings under the Control Plane or Advanced sections.

Advantages

• No password to rotate. The key is long-lived until revoked.

• No MFA concerns. API keys bypass the authentication flow entirely.

• Simpler integration setup: one key instead of a username + password pair.

• Cleaner from a security audit perspective: keys can be individually revoked without affecting other accounts.

Disadvantages

• Still requires direct connectivity, with the same firewall and networking considerations as local admin.

• Requires the latest version of your Art of WiFi product; older releases only support local admin credentials.

• If the key leaks, it grants access until manually revoked. There is no automatic expiry.

• API key scope and permissions may differ from what you're used to with the classic API; verify your use case works.

When to use

When you have a direct connection and want to simplify credential management. Particularly attractive for new deployments, automated provisioning, or environments where password rotation is operationally costly.

Method 3: Site Manager API Key (connection via unifi.ui.com)

How it works

Instead of connecting directly to the console, your integration connects to unifi.ui.com using a Site Manager API key. Ubiquiti's cloud infrastructure proxies the request to your console. The console itself doesn't need to be reachable from your integration host.

Requirements

• Latest version of your Art of WiFi captive portal or UniFi Device Search Tool (other products will be updated soon).

• Your console must be adopted to a UI.com account and connected to Ubiquiti's cloud (the default for most setups).

• A Site Manager API key generated at unifi.ui.com.

• Internet access from your integration host (outbound HTTPS to unifi.ui.com).

• A UniFi OS console or UniFi OS Server. The legacy self-hosted Network Application is not supported via Site Manager.

How to create a Site Manager API key

1. Go to unifi.ui.com and log in with your UI.com account.

2. Navigate to Site Manager → API (or look for API settings in the top-level menu).

3. Generate a new API key with an appropriate scope.

4. Copy and securely store the key.

Advantages

• No direct connectivity required. This is the key differentiator. Your console can sit behind CGNAT, a dynamic IP, or a restrictive firewall. As long as it's cloud-adopted, Site Manager can reach it.

• No firewall rules to manage on the console side.

• One API key can potentially access multiple sites/consoles under the same UI.com account.

• Ideal for managed service providers (MSPs) overseeing many client sites.

Disadvantages

• Depends on Ubiquiti's cloud infrastructure. If unifi.ui.com is down, your integration can't reach the console.

• Slightly higher latency compared to direct connections (requests are proxied).

• The console must remain cloud-adopted; if someone disables cloud access, the connection breaks.

• API coverage through the Site Manager proxy may differ from what's available via direct connection. Verify your specific endpoints work.

When to use

When direct connectivity isn't possible or practical. Common scenarios include: consoles with dynamic WAN IPs and no DDNS, ISPs using CGNAT (increasingly common with IPv4 exhaustion), MSPs managing dozens or hundreds of remote client sites, and hosted or distributed environments where opening inbound firewall rules is not an option.

Side-by-side comparison

Migrating from local admin to an API key method

If you're currently using a local admin account and want to switch:

1. Generate the appropriate API key (Network Application or Site Manager, depending on your connectivity situation).

2. Update the connection settings in your Art of WiFi product. This is done through the site authentication configuration: select the new connection type and enter the API key.

3. Test the connection. Verify that your captive portal, reports, or device queries work as expected.

4. Keep the local admin account as a fallback until you're confident the new method is stable. You can disable or remove it later.

There is no need to migrate if your current setup works and you're satisfied with it. All three methods will continue to be supported.

Further reading

• Use a Local Admin Account for UniFi API & Captive Portal Integrations (step-by-step local admin setup guide)

• Art of WiFi UniFi API Client on GitHub (source code, changelog, and API reference)

• Art of WiFi Captive Portal Solutions (our full captive portal product line)

• UniFi Device Search Tool (search and manage devices across your UniFi network)