Getting started with UniFi

This walkthrough connects your first controller and assigns its sites to customers. You need the UniFi manage permission for assignments, and tenant settings access for the controller credentials.

1. Create an API key on the controller

On the controller, open Settings > Control plane > Integrations and create an API key. The key only needs read access for now. Managed actions arrive in a later phase with their own credential.

For customer-owned controllers, the controller must be reachable from concorbit over HTTPS on a public address. Private or internal addresses are rejected for safety.

2. Connect the controller

1. Go to Settings > Integrations > UniFi

2. Choose Add controller

3. Pick the type: Shared for your own multi-customer controller, Customer-owned for a box that belongs to one customer

4. Enter the controller URL (for example https://unifi.example.com:8443) and the API key

5. Untick Verify TLS certificate only if the controller uses a self-signed certificate

6. Save, then choose Test connection

A successful test queues the first site sync. Within a minute or two the connection card shows how many sites were discovered.

3. Assign sites to customers

1. Open UniFi in the sidebar

2. Pick the customer (or the pinned Internal entry for your own sites)

3. Choose the controller, then the site (sites already assigned to another owner are shown and cannot be picked twice)

4. Optionally link the assignment to one of the customer's premises records

5. Assign

The customer's row on the UniFi page now shows their site and device counts.

4. Set the toggles

Each assignment carries four switches: View (on by default), Adopt, Basic changes, and Public WiFi. The last three gate managed actions that ship in a later phase. Setting them now means the right customers are enabled the day the actions arrive.

5. Day-to-day

• Open an assignment to see its devices: state, model, IP, firmware, and anything waiting for adoption. The list refreshes every 30 seconds.

• Refresh now (manage permission) queues an immediate controller sweep.

• The UniFi sites and UniFi devices canvas panels bring the same data onto your canvas and dashboard; clicking a site sets the company context for every other panel.

Troubleshooting

• Connection test fails: check the URL includes the right port (often 8443) and the API key was copied in full. The connection card shows the last error.

• No sites discovered: the API key may lack access on the controller, or the first sync is still queued; test the connection again.

• A site is missing from the picker: sites appear after a sync. Run one from the settings page, then reopen the picker.

• Devices show as gone: devices missing from the controller for more than the grace window are flagged inactive but never deleted; they reactivate automatically when they reappear.