Before you begin
- An Enterprise plan or above. The Integrations hub is locked below Enterprise
- The Administrator role in Atlas to connect, configure or disconnect a connector. Integrations appears under Administration only for administrators
- A tenant selected in the tenant picker. Credentials are stored encrypted per tenant, so each tenant you manage connects its own account
- For a cloud connection: a UniFi Site Manager API key from unifi.ui.com. Consoles need firmware 5.0.3 or later to list their sites
- For a local connection: an API key created on the console, and the console's public https address with a publicly trusted certificate
- To sync into Vault: a Vault admin and at least one asset template (the Network Device template is a good fit)
What you can do
- Document every gateway, switch and access point on a UniFi site as an Atlas Vault asset, with no manual data entry.
- Map each UniFi site to the customer company it belongs to, so an MSP keeps every customer's network documentation separate.
- Keep the documentation current: every hour Atlas adds new devices, updates changed details and archives devices UniFi no longer reports.
- See what changed and when: firmware, management IP, name, site and uplink changes, each with the previous value kept.
- Search Vault for a device by name or by any mapped detail, such as model, MAC address or management IP.
- Ask Atlas Advisor about documented equipment, for example "What UniFi switches does Contoso have?"
Step 1: Choose cloud or local, and create an API key
A UniFi key only works for the connection type it was created for.
- Cloud (recommended for MSPs): in unifi.ui.com, go to Settings → API Keys and create a key. An organization key can read every console in the organization; a personal key reads only the consoles you own. Atlas reaches each console through UniFi's cloud, so nothing needs to be opened on the customer's network.
- Local: on the console, go to UniFi Network → Settings → Control Plane → Integrations and create a key. Atlas then calls that one console directly, so it must be reachable from the internet at an https address with a publicly trusted certificate. Atlas refuses private and internal addresses and never skips certificate checks. If the console is on a private network, use a cloud connection instead.
Step 2: Connect in Atlas
Once connected, the card shows Manage, which opens Atlas Vault → Assets, and Disconnect. The key is stored encrypted and is never shown again.
- Select the tenant in the tenant picker.
- Go to Administration → Integrations and click Connect on the Ubiquiti UniFi card.
- Choose the Connection type. For Local, enter the Console address, for example https://unifi.example.com.
- Paste the API key and click Connect. Atlas reads your consoles and sites with the key before saving anything; if UniFi rejects it, nothing is stored.
Step 3: Map each site to a company
Add one sync per site. A site can be mapped only once in a tenant, so its equipment can never end up under two companies. When your customers live in separate Atlas tenants, connect UniFi in each tenant; a tenant only ever sees its own UniFi connection, syncs and assets.
- Open Atlas Vault → Assets → RMM & PSA sync and click Add sync.
- Source: Ubiquiti UniFi.
- Device type: pick a site. A cloud connection lists every console's sites as Console — Site. A console UniFi's cloud can't reach for site details (older firmware) is offered once as Console (all devices).
- Template: pick Network Device. Atlas fills in the field mappings for you: Name, Type, Manufacturer, Model, Management IP, Firmware Version and Location (the UniFi site). You can change or add any mapping.
- Company: the customer this site belongs to.
- Leave Sync automatically every hour on, click Save Changes, then click Run now to document the site straight away.
What gets documented
- Identity: name, manufacturer (Ubiquiti), model and model code, MAC address.
- Type: Gateway, Switch or Access Point, plus every role a device has (a gateway with switch ports is both).
- Network: management IP, UniFi site and console.
- Software: firmware version and whether an update is available. On a cloud connection, the firmware status and the version of the available update too.
- Operational: status (online, offline, updating and so on), adoption and provisioning times, and last start time.
- Connected equipment: the device UniFi reports as this one's uplink, such as the switch an access point connects through.
- The note entered on the device in UniFi.
Each device is matched by its MAC address, so renaming it, changing its IP, re-adopting it or moving it to another site updates the same asset instead of creating a new one. UniFi does not report serial numbers, so Atlas does not fill one in; you can add it by hand. Connected clients such as laptops and phones are not documented.
Your own documentation is kept
Atlas only fills the fields you map. Notes, attachments, custom fields and anything else you add in Vault are yours and are never touched. If you edit a mapped field by hand, Atlas keeps your value; if UniFi later reports something different, the field is flagged under Drift to review so you can choose which to keep. A device UniFi stops reporting is archived, not deleted, and comes back automatically if it returns. Atlas archives a device only after a complete read of the site, so an outage or a rejected key never empties your documentation. Archiving needs the sync to be the only UniFi sync using its template: when several UniFi syncs share one template, Atlas can't tell which site a missing device belonged to, so it leaves those assets in place for you to archive by hand.
Change history
Open an asset's ⋯ menu and choose History to see what UniFi changed: when the device was first documented, a new name, management IP, firmware, site, console or uplink (each with the previous and new value), when it was no longer reported, and when it came back. Routine online and offline changes and restarts are not recorded, so the history only shows changes that matter. The same entries appear on the Operations Timeline. History records changes to fields that are mapped on the template, starting from the first sync after you connect. When a first sync documents more than 25 devices, the timeline shows one summary entry instead of one per device.
Ask Atlas Advisor
Atlas Advisor answers questions from the documented assets, read-only and limited to what you can see in Vault. For example: "What UniFi switches does Contoso have?", "What's the management IP of the main office gateway?", "Show all network equipment at the Main Office site" or "Which UniFi devices haven't synced recently?". To ask about pending firmware updates, add a field such as Firmware Update Available to your template and map it from firmware_update_available. The Network Device template does not include one.
What the integration does not do
- It is read-only. It never adopts, restarts, upgrades or reconfigures a UniFi device.
- It does not document connected clients (laptops, phones and other endpoints).
- It does not document serial numbers, because UniFi does not report them.
- It does not infer physical cabling; the only connection shown is the uplink UniFi reports.
- It does not show UniFi alerts, and it does not create tickets.
- It syncs every hour or when you click Run now; the interval cannot be changed.
- It does not archive missing devices automatically when several UniFi syncs share one asset template.
- It connects one UniFi account per Atlas tenant. Credentials cannot be edited in place: disconnect and connect again with the new key.
GCC High tenants
On a tenant or deployment in Azure Government (GCC High), calls to UniFi are blocked by default, because they can carry VM, host-pool and tenant names to a service outside the Government boundary. Connect fails with an Azure Government (GCC High) egress boundary message and nothing is stored, and pages that read from UniFi stay empty. The operator who runs your Atlas deployment can approve UniFi as a destination that is allowed to receive that data; once approved, the connector works normally. Running in Azure Government does not by itself make a third-party integration GCC High or CMMC compliant.
Disconnecting
Click Disconnect on the card and confirm. Atlas deletes its stored copy of the API key and pauses every Atlas Vault sync from UniFi. The documented assets and their history stay in Vault; turn the syncs back on after you reconnect. Nothing changes in UniFi. Delete or revoke the key in UniFi too if you no longer need it.
Troubleshooting
- UniFi rejected the supplied credentials: the key is wrong, has been revoked, or was created for the other connection type. Create a new key of the right type and connect again.
- consoleUrl must be the console's https:// address: a local connection needs the console's public https address, for example https://unifi.example.com.
- UniFi is temporarily rate limiting requests — try again shortly: wait a minute and try again. Scheduled syncs retry with backoff on their own.
- Could not connect to UniFi — verify the server URL and credentials: UniFi or the console could not be reached. For a local connection, check that the address is public and its certificate is publicly trusted.
- The Device type list shows a console as (all devices): UniFi's cloud could not read that console's sites, usually because its firmware is older than 5.0.3. Update the console's firmware to map its sites one by one.
- Some devices have no uplink or adoption time yet: on a cloud connection Atlas reads those details for up to 60 devices per site on each sync, to stay within UniFi's limits, and moves on to the next 60 devices on the following sync. A larger site has every device covered within a few hourly syncs, and a device keeps the details it already has in between.
- A sync reports the integration is not configured: UniFi was disconnected. Connect it again, then turn the sync back on.