Skip to main content
Save one UniFi connection at the MSP level, then enable access per agent. Choose credentials for the API your controller exposes.

​
Which setup applies to you

The legacy login was verified in a lab running Network 10.6.101. That lab did not expose API-key creation; this does not establish a limit for every self-hosted deployment. HostiFi compatibility is unverified. Confirm the API your deployment exposes before choosing a connection type.

​
1. Create an API key in UniFi Site Manager

1

Sign in to unifi.ui.com

Use the UI account that manages your customers’ consoles. The key sees exactly the consoles that account can manage — for an MSP that is usually the organization owner account.
2

Create the key

Open Settings → API Keys and click Create New API Key.
Copy the key somewhere safe once it’s generated — UniFi shows it only once.

​
1b. Or: create an API key in your UniFi OS console

1

Sign in to the controller

Open your UniFi OS Server or console in the browser. This connection uses its Network Integration API at /proxy/network/integration/v1/. A controller URL alone does not establish that this API is available.
2

Create the key

Open Settings → Control Plane → Integrations and click Create API Key. Copy it once it’s generated — it is shown only once.
The key inherits the permissions of the admin who creates it, so create it from an account that can see every customer site you want Neo to work on.
A Site Manager key and a console-created key serve different APIs. Use the console-created key for a direct connection.

​
1c. Or: use a local controller admin

Create a dedicated local admin on the self-hosted Network Server, with access only to the sites Neo needs. Enter that account’s username and password in Neo. This login cannot answer an MFA challenge; use a dedicated account compatible with password-only login, subject to your security policy. Neo logs in through /api/login and uses the returned session cookie for the legacy API. You do not enter a cookie or an API key. Both URL connection types reach one controller’s Network application. They do not provide the Site Manager fleet views or cloud ISP and SD-WAN endpoints. Available network operations depend on the controller’s API and version; the legacy API does not have the same endpoints as the modern Integration API.

​
Controller URL and TLS

Use the controller root, including its port, such as https://unifi.example.com:8443. Omit browser paths such as /manage. The URL must be reachable from Neo’s backend and present a certificate trusted by that backend, with a matching hostname. TLS certificate verification stays enabled for credential checks, legacy login and subsequent requests. Neo has no option to bypass verification. A private address reachable only from your workstation will not work without a network route from Neo.

​
2. Add the credentials in Neo

1

Open Integrations

Open Integrations and find Ubiquiti UniFi under Networking.
2

Save the credentials

Select Connection type and enter the fields listed above. Click Save. Neo checks Site Manager access, direct Network site access, or the legacy login and site list before it stores the connection.

​
3. Turn UniFi on per agent

Each agent decides whether it uses UniFi and which areas it can touch. Open the agent, go to the Integrations section, and configure the UniFi block.

​
Pick an access profile

Read Only

Every area set to read only. The agent can look up consoles, sites, devices, clients, networks and firewall rules, but never makes changes.

Helpdesk

Hotspot Vouchers and Clients read and write — issuing a voucher goes through on its own; authorizing a guest still waits on a technician. Devices, networks and firewall read only.

IT Admin

Every writable area read and write, but every write waits on a technician. A cautious rollout tier.

Full Automation

Issuing vouchers goes through on its own. Device restarts, network or firewall changes, guest authorization and voucher deletion still always require technician approval — that never turns off.

​
Or set each area by hand

These groups cover the APIs Neo exposes. The selected connection type and controller version determine which operations are available. Fleet inventory, cloud ISP metrics and SD-WAN require Site Manager; legacy controllers use their own device, client, network, firewall and voucher endpoints.

​
Safety controls

  • Device restarts, adopt/unadopt, PoE power-cycles, every network or firewall change, guest authorization and voucher deletion always wait on a technician. This holds regardless of the agent’s automation level or the access profile you picked.
  • Consoles & Sites is always read only. Neo does not expose site creation or deletion.
  • Only the Network application is reachable. Protect (cameras) and other UniFi applications are not exposed to agents.
  • Path safety. Suspicious URL paths (anything containing .., for example) are rejected before they reach UniFi.
  • Company mapping. Neo matches UniFi site names to PSA companies during PSA metadata sync. With Site Manager, a site still named “Default” that is the only site on its console is matched by the console’s name instead, when the console reports one; a “Default” site on a console with several sites keeps its own name. Review matches on Organization Mapping, especially after a change of connection type. Legacy requests use the site’s name slug (for example default); modern direct requests use its Integration API UUID. These identifiers are not interchangeable.
  • Rate limiting. Neo paces calls at 100 requests per minute per Connector console, or in a shared bucket for calls without a Connector console ID.

​
If UniFi refuses Neo’s requests

Until it is fixed, agents that use UniFi report the failure on the ticket they were working. The rest of Neo keeps running.

​
Disconnecting Ubiquiti UniFi

1

Open the integration

In the Neo Dashboard, open Integrations and select the Ubiquiti UniFi card.
2

Disconnect

Click Disconnect and confirm. Neo removes the credentials from Key Vault.
Your Organization Mapping is kept, including any mapping you set by hand, so reconnecting later picks up where you left off. Agents that use Ubiquiti UniFi stop working until you connect it again.

​
Security

  • Neo stores connection credentials in Azure Key Vault. A self-hosted login is exchanged for a session cookie, cached for 20 minutes per tenant, controller URL and admin account. The password itself is never cached. Changing the Controller URL or the admin retires the cached session.
  • All traffic goes over HTTPS. In the Site Manager setup calls go to api.ui.com and per-console calls are proxied by Ubiquiti’s cloud Connector, so Neo never connects to a console directly. With a Controller URL, Neo connects to that controller over HTTPS with TLS certificate verification enabled. http:// URLs are refused.
  • Write access to UniFi is opt in per area, per agent.
Once your credentials are saved and an agent has permissions, the UniFi tool is added to that agent automatically.