Ubiquiti UniFi network integration
Monitor switches, access points, and gateways from UniFi OS consoles — one integration per client site.
What you get
After connecting a UniFi controller, Allocentra syncs adopted network devices (gateways, switches, access points) into Network. Devices refresh automatically every 15 minutes, or you can sync manually from the Network overview.
- Online/offline status, model, firmware, IP, and MAC per device
- One integration per controller — ideal for each client head office or site
- MSP: assign the integration to a managed client so devices appear under that client
Before you start
- A UniFi OS console (UDM, UDM Pro, UCG, etc.) registered to your Ubiquiti account at unifi.ui.com
- Console online and reachable by Ubiquiti Site Manager (firmware 5.0.3+ recommended for remote API)
- A Site Manager API key — not the local Integrations key from the UDM settings page
API keys — do not mix these up
| Key type | Where to create | Used for |
|---|---|---|
| Site Manager API key | unifi.ui.com → Settings → API Keys | Allocentra cloud connection (required) |
| Local Integrations API key | UDM → Settings → Control Plane → Integrations | Direct LAN API only — not for Allocentra cloud |
Add an integration (recommended — cloud)
- In UniFi Site Manager, go to Settings → API Keys and create a key with read access. Copy it immediately — it is shown only once.
- In Allocentra, open Network → Add integration.
- Select vendor Ubiquiti UniFi.
- Connection type: Cloud (Site Manager — recommended)
- Integration name: e.g.
Acme Corp — Head Office UniFi - Site Manager API key: paste the key from unifi.ui.com
- Console ID: leave blank — Allocentra discovers your site from the API key
- Site name:
default(unless the site uses another name in UniFi) - MSP only: link the integration to the correct managed client when creating it.
- Click Test & add integration.
For MSP workspaces
Repeat these steps for each client that has their own UniFi controller. One integration = one physical site/controller. If a client has multiple offices with separate UDMs, create one integration per office.
For Internal IT workspaces
Create a single integration for your organisation's UDM. No client selection is required.
Local connection (advanced)
Local mode connects directly to the controller URL. Allocentra runs in AWS and cannot reach private LAN addresses (192.168.x.x) or *.id.ui.direct hostnames — those only work on your office network.
Use local mode only if the controller has a public hostname or IP with firewall rules allowing HTTPS from the internet, plus a local Integrations API key from the UDM.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Failed to resolve *.id.ui.direct | LAN-only DNS hostname | Use Cloud mode, not local URL |
| 403 Forbidden on connector URL | Wrong console ID or key | Leave Console ID blank; use Site Manager key from ui.com |
| 401 Unauthorized | Invalid or wrong API key type | Create a new key at unifi.ui.com → Settings → API Keys |
| 404 on /sites/.../devices | Outdated API path (fixed in product) | Re-test sync — cloud mode uses GET /v1/devices |
| No devices returned | Console offline or empty site | Confirm devices are adopted in UniFi; check console is online at ui.com |
| Site 'default' not found | Site name mismatch | List sites in UniFi and enter the exact site name |
Security notes
- Store API keys only in Allocentra — rotate if exposed.
- Site Manager keys are read-only at GA; device reboot via cloud is not supported yet.
- Revoke unused keys in unifi.ui.com if you remove an integration.