Connect UniFi

Ubiquiti's UniFi platform is really four products sharing one cloud account: Site Manager (the console and site inventory that ties everything together), Network (switching, WiFi, VLANs, firewall and guest access), Protect (cameras, sensors, sirens and alarms) and Mobility (mobile-routing workspaces and devices). StackJack connects to all four through Ubiquiti's official cloud API at api.ui.com, using a single API key you create once.

Connecting UniFi gives your AI a broad set of unifi_ MCP tools — MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:

• Find your equipment — list every UniFi console you can reach, the sites on each one, and the devices across all of them
• Investigate the network — adopted and pending devices, live client lists, per-device statistics, VLANs, WiFi broadcasts, VPN servers and tunnels, link aggregation and switch stacks
• Read and change policy — firewall policies and zones, access-control rules, DNS policies and traffic-matching lists, including the order they are evaluated in
• Run guest WiFi — generate, list and revoke hotspot vouchers, and authorize or cut off individual guests
• Act on hardware — adopt a device, restart it, or power-cycle a single PoE switch port
• Watch the premises — list cameras, sensors, lights, chimes, speakers, viewers and live views; take a camera snapshot; read stream URLs
• Work the alarm system — arm and disarm, switch arm profiles, sound or silence a siren, trigger an alarm-hub output, and move PTZ cameras to stored presets
• Check ISP health — per-site internet performance metrics and SD-WAN configuration status
• Manage Mobility — list workspaces, devices and their clients, and update a device's name, LAN/DHCP settings or wireless configuration

What works today, and what needs more than a key

Set expectations before you configure anything, because UniFi draws a line most people do not expect:

• Site Manager tools work with any valid cloud key. Listing consoles, sites and the device inventory, ISP metrics and SD-WAN status — these ask the UniFi cloud directly and need nothing beyond the key.
• Network and Protect tools need more. Those calls are relayed to one specific console, and UniFi only relays to a console when your key's account owns it. A key that can list a console does not imply it can manage that console. Where it cannot, you have two ways in: a key from the console's owner, or a direct connection to the controller.

The three kinds of UniFi key

This is the single biggest source of confusion, so it is worth learning up front: there are three cases, and the first two are not interchangeable.

Pasting a local console key into the API Key field is a common mistake, and it fails loudly: every call returns 401 {"code":"unauthorized","httpStatusCode":401,"message":"unauthorized"}.

If you are hunting for Settings → Control Plane → Integrations on a self-hosted controller and cannot find it, stop looking. That page exists on UniFi OS only — consoles and UniFi OS Server. The older Network Application does not have it, and no amount of upgrading the Network application adds it.

Which lane am I on?

How StackJack authenticates to UniFi

UniFi uses a static API key — the key alone authenticates every call. There is no client ID, OAuth consent, or refresh flow. Ubiquiti's current public getting-started guide does not publish an automatic expiry for Site Manager keys; revoke and replace the key when your policy requires rotation or if it may have been exposed.

The cloud endpoint is fixed at https://api.ui.com, so there is no regional URL to get right. The only URL you may need to enter is a direct controller's, and that is optional.

Read this before you create the key

Two separate things decide how much of the connector works, and both produce no error at setup time.

Personal vs organization decides what you can see:

If you manage customer equipment across several owners — the normal situation for an MSP — create the key inside your organization, not as an individual. A personal key will look like it works: it authenticates fine and returns a console list. That list is just quietly short.

Owner vs admin decides what you can manage, and this one surprises nearly everyone:

Being an admin on a console is not enough — not even a full admin with every application permission. UniFi's cloud relays a request to a console only when your key's account is that console's Owner. An admin-only key lists the console perfectly well and then fails on every Network and Protect call against it with forbidden: access denied: user is not the owner of this host.

Create the key from the account that owns the consoles you intend to manage. A console's Settings → Admins & Users page shows which account that is. If ownership sits with someone else, that is what the per-console keys and the direct lane are for.

Before you begin

• In StackJack: you need a role that can manage connectors (tenant Owner, a co-owner, or an Administrator).
• In UniFi: you need an account that can create API keys — ideally the account that owns the consoles you intend to manage, in the organization those consoles belong to.

Step 1 — Create the API key in UniFi

1. Sign in at unifi.ui.com with the Ubiquiti account that manages your consoles.
2. Go to Settings → API Keys.
3. Decide personal or organization first — see the table above. For an MSP, create the key inside your organization.
4. Make sure you are signed in as the account that owns the consoles you intend to manage, not merely an admin on them. This decides whether Network and Protect tools will work at all, and it cannot be changed by editing permissions afterwards.
5. Choose Create API Key and give it a name that identifies StackJack.
6. If the dialog offers a site scope, choose "All Sites" (newer Site Manager releases, 5.0/5.1 and later, let a key be limited to specific sites at creation — including Fabrics-grouped sites). A key scoped to particular sites is silently blind to every other site, which looks exactly like missing equipment later. Narrow it only when you genuinely intend that key to manage a subset.
7. Copy the key immediately and store it securely. UniFi shows it only once, and anyone holding it can read and act on your UniFi equipment.

Step 2 — Add the credentials in StackJack

1. In the StackJack portal, open Connectors.
2. Find the UniFi card. Click How To Connect for these steps inline, or Configure to enter the credentials.
3. Paste the key into API Key. UniFi's cloud endpoint is fixed, so there is nothing to enter for it.
4. Leave Mobility API Key empty unless you use UniFi Mobility and your main key does not cover it (see below).
5. Leave Per-console API Keys and the three Direct Controller fields empty for now. They exist for consoles your own key cannot manage — see Which of my consoles will actually work? once you have saved, which tells you whether you need them at all.
6. Click Save.

The optional Mobility key

UniFi Mobility is gated by its own application permission. If your main key does not cover it, create a second key that does and paste it into Mobility API Key. Leave the field empty if you do not use Mobility.

On an edit this field always starts blank, and leaving it blank keeps whatever is already stored — so rotating your main key never forces you to re-enter the Mobility one.

What happens when you save

• The API key is stored encrypted in Azure Key Vault — never in the StackJack database, and never shown back to you.
• If this is the first time you configure UniFi, a Free-tier subscription for the connector is created automatically so its Free tools work right away.
• StackJack immediately live-validates the key by listing your consoles. Validation never blocks the save: you will either see a success confirmation or a "saved but validation failed" warning with the reason.

The validation read is the console list, which is also the discovery call your AI makes first. A success here proves the key works and shows you immediately whether it reaches the consoles you expected — which is exactly how you catch a personal key that should have been an organization key.

Finding your console ID

Network and Protect calls are relayed to one specific console, so every Network and Protect tool needs a console ID. Site Manager and Mobility tools do not.

Your AI discovers these itself: List UniFi Consoles (Hosts) returns every console the key can reach, and each host is a console. Ask your AI to list them once and it can work from that list afterwards. A console ID is a long hexadecimal string with a colon and a numeric suffix — pass it through exactly as returned, including the colon.

If a console you manage does not appear in that list at all, the key is the reason, not the console. See the personal-vs-organization table above.

Which of my consoles will actually work?

Do this once, right after saving the key. It turns a mystery 403 into something you can see in advance.

Ask your AI to list your UniFi consoles, and read the owner flag on each one:

A console with owner: false looks completely healthy — it is listed, it reports its firmware and its applications, and nothing about it says "you cannot use this." Being an admin on it, even a full admin with every application permission, does not change the flag. The flag is the honest answer, so check it before you plan work around a console.

Reaching consoles your key does not own

Every console showing owner: false has three ways forward, best first.

First, tell the two situations apart. A console listed with owner: false and a console not listed at all are different problems. Per-console keys widen what you can manage — they never widen what your main key can discover: the console list always comes from your main key, and a per-console key is consulted only for requests addressed to that console's ID. So for a console your key cannot even see, options 2 and 3 still work, but you must get the console ID from its owner (their own console list shows it) — it will never appear in yours, and that is expected, not a fault. A key limited by a site scope (see Step 1, item 6) is the other common reason a console is missing entirely.

1. Use a key from the account that owns it. Ownership, not permissions, is the deciding factor — so either create your Site Manager key from the owning account, or have ownership transferred to the account whose key you already use. A console's Settings → Admins & Users page shows which account is the Owner. This is the only fix that needs nothing further afterwards — and the only one that also fixes discovery.

2. Add a per-console key. Ask that console's owner to create an API key at unifi.ui.com exactly as you did, and paste it into Per-console API Keys as console id=key, one per line. That key is used only for requests to that console; everything else keeps using your own. Copy the console ID exactly, colon suffix included — from your console list when the console is visible to you, or from the owner's when it is not.

Leaving the Per-console API Keys box empty on an edit keeps every key already stored. To remove one, enter its console ID with nothing after the equals sign.

3. Connect to the controller directly — see the next section. This is also the only option for a console that is not maintaining its cloud connection at all.

Connecting directly to a controller

If a UniFi OS console or a UniFi OS Server is published on the internet with a valid certificate, StackJack can talk to it without going through the UniFi cloud:

1. In Direct Controller URL, enter its address as scheme, host and port only — for example https://unifi.example.com:8443. Do not add a path.
2. Set Direct Controller Type to UniFi OS Server (self-hosted), or UniFi OS console for a Dream Machine, Cloud Key or UNVR.
3. Create a second key on that controller, under Settings → Control Plane → Integrations, and paste it into Local API Key. This is a different key from your unifi.ui.com one, and the two are never substituted for each other.

Your AI then reaches it by using the word local where a console ID would normally go — so "list the sites on the local controller" works the same way "list the sites on console X" does.

Four things to know:

• The legacy self-hosted UniFi Network Application cannot be connected this way, or any other way. It has no Settings → Control Plane → Integrations page, so there is no API key to create for it. Its API routes exist and answer, but every call is refused because no valid key for them can exist. UniFi OS Server is the supported self-hosted product.
• The address needs a valid public certificate. StackJack will not connect to a controller presenting a self-signed one.
• The address must be a public one. StackJack reaches your controller from the internet, so a local-network address such as 192.168.1.1, 10.0.0.5 or 127.0.0.1 — or the name localhost — is refused when you save, because nothing outside your network could ever reach it. Publish the controller at a name or address that resolves on the internet. A name of your own that happens to point at a private address is accepted at save time and simply fails to connect.
• UniFi Protect is available on the console type only. A self-hosted server serves its API at a path with no application segment, so it addresses UniFi Network and nothing else.
• Site Manager and Mobility tools always use the cloud. Those are Ubiquiti cloud services with no on-controller equivalent, so they still need your unifi.ui.com key.

If a direct controller is the only UniFi equipment you are connecting, you can leave API Key empty and configure just the direct controller. Everything that needs the cloud will then tell you a cloud key is required, rather than failing obscurely.

Plans and available tools

• Free includes console, site and device inventory across all products; ISP metrics and SD-WAN status; Network clients, devices, VLANs, WiFi broadcasts, firewall policies and zones, access-control rules, DNS policies, traffic-matching lists, VPN, switching and reference data; Protect equipment and NVR details; and Mobility workspace, device and client listings.
• Pro adds write, action and sensitive-read operations for networks, WiFi broadcasts, firewall and ACL rules, DNS policies and traffic lists; device adoption, restart and removal; switch-port power cycling; guest authorization; hotspot vouchers; Protect device settings, PTZ movement, sirens, alarms and relays; Mobility device changes; and raw console relays.
• Business offers the same tools as Pro with a higher usage allowance.

See the generated UniFi tool reference for the current inventory, plan assignment, input schemas, and destructive-action labels.

UniFi has no per-user sign-in for its API, so all AI traffic authenticates as the single API key — there is no per-user attribution. Current pricing and quotas are shown in the portal's Billing page and at checkout.

Three things to know about the tiers

A few reads are Pro tools even though they change nothing. Reads are otherwise Free, and these are the deliberate exceptions, each one paid for what the answer contains rather than what the call does:

The raw console-relay tools are Pro, and StackJack marks the read operation as a change too. This family forwards a request you specify straight to a console for endpoints StackJack has no purpose-built tool for. Write operations carry the marking for the obvious reason. The read operation carries it as well, because you choose the address it calls and some UniFi read endpoints have side effects. Prefer a purpose-built tool whenever one exists: they validate what you pass, cap page sizes, and describe what comes back.

Know which actions are disruptive before you grant them. StackJack marks every delete, device restart, and port power-cycle as a change. Whether your AI application asks you to confirm before running one depends on that application's own settings — see Destructive tools and confirmation. Review those settings, and grant only what you want an AI to reach. A few are worth calling out specifically, because the name does not tell you how far they go:

• Remove (Unadopt) Device performs a factory reset on a device that is online, not merely an unadopt.
• Reorder Firewall Policies and Reorder ACL Rules replace the whole ordered list. An incomplete list silently drops rules out of enforcement rather than erroring.
• Siren and alarm controls are marked in both directions — sounding or silencing a siren, and arming or disarming the alarm, all change the security posture of a real premises.
• Permanently Disable Camera Microphone cannot be undone without a factory reset of the camera.
• Replace Mobility Device SSID and Password drops every client currently connected to that device.

Rate limits and the relay's two hard limits

Each console accepts 100 relayed requests per minute. StackJack paces requests and backs off on its own, which smooths a burst — a wide sweep across one console may just take a little longer. Pacing is not a guarantee that every call gets through: retries are bounded, and a wide enough sweep can still come back throttled. Narrow the read, honour the retry delay UniFi sends, and check whether a write landed before repeating it — see Retrying a failed or timed-out write.

Relayed Network and Protect calls also carry two limits set by Ubiquiti that StackJack cannot work around:

• A request must finish within 25 seconds. A very broad list against a busy console can exceed this.
• A response larger than 10 MB is not returned.

Both have the same fix: ask for a narrower page or a tighter filter. Site Manager and Mobility calls are not relayed and are not subject to either limit.

Filtering by names containing & or #

Many UniFi Network tools accept a server-side filter expression, and names like Bed & Breakfast or R&D work normally in one. StackJack percent-encodes a literal & or # before sending, because those two characters delimit the request itself — left raw, either one cuts the filter short, and a shorter filter matches more, which on a voucher delete would destroy more than you asked for. UniFi decodes them correctly on the other side, so the filter you write is the filter that runs. Verified live against a UniFi console.

Rotating or replacing the credentials

The API key is the only secret. If you regenerate or revoke it in UniFi, the stored credential stops working. To restore access, open Connectors → UniFi → Configure, paste the new key, and Save.

If you are only adding or changing the Mobility key, leave the main API Key field blank and save — StackJack keeps the key it already has. The same applies to Local API Key and every entry in Per-console API Keys: a blank field keeps what is stored.

Because a blank field keeps the key rather than removing it, removing one has its own control. Tick Remove the stored cloud API key, leave the API Key field empty, and save. Do that only when you have revoked the key at unifi.ui.com or are moving to a direct controller alone — UniFi Site Manager, Mobility and every console addressed by ID stop working, and UniFi cannot show you the old key again. StackJack refuses the save if it would leave the connector with no way in at all, so configure the direct controller first.

One exception. If you change the Direct Controller URL, StackJack asks you to re-enter the Local API Key on that save rather than carrying it over — that key belongs to the controller you are moving away from, and a key is never carried to a new address. Your cloud keys are unaffected: the main API key, the Mobility key and every per-console key stay stored, because they answer to UniFi's cloud rather than to the controller you changed.

What the UniFi API does not expose

Worth knowing up front, so you do not go looking for tools that cannot exist:

• Protect has no event history. There is no way to ask the API what happened last night — no motion events, no detections, no recording index. The connector can tell you what the equipment is and change what it does, not what it saw. Ubiquiti exposes events only over a live streaming connection, which a request-and-response tool cannot consume.
• There is no way to read a PTZ camera's current position, or to list its presets. Moving a camera is therefore not reversible through the API, and StackJack cannot tell you in advance whether a camera supports PTZ at all or which preset slots are configured. Slot -1 is the home position; 0 and above select a stored preset.
• Firewall zones and ACL rules created by UniFi itself cannot be edited. Only ones you defined are mutable.
• Switching is read-only. UniFi publishes no create, update or delete for link aggregation groups, MC-LAG domains or switch stacks.
• Protect events, PTZ positions and UniFi-created firewall rules stay out of reach whichever way you connect — the direct controller lane changes which equipment StackJack can talk to, not what the UniFi API offers.
• A controller on a private network cannot be reached at all. The direct controller lane needs a publicly resolvable address with a valid certificate; a hosted service cannot see 192.168.x.x, and StackJack will not accept a self-signed certificate.

Troubleshooting

UniFi tools

unifi_ · 167 tools · Free 85 · Pro 82

UniFi Hosts & Sites

UniFi Device Inventory

UniFi ISP Metrics

UniFi SD-WAN

UniFi Console Proxy (raw)

UniFi Mobility Workspaces

UniFi Mobility Devices

UniFi Network Application Info

UniFi Network Sites

UniFi Network Reference Data

UniFi Network VPN

UniFi Network Devices

UniFi Network Clients

UniFi Network Networks (VLANs)

UniFi Network WiFi Broadcasts

UniFi Network Hotspot Vouchers

UniFi Network Firewall

UniFi Network Access Control

UniFi Network DNS Policies

UniFi Network Traffic Matching Lists

UniFi Network Switching

UniFi Protect Cameras

UniFi Protect Camera PTZ

UniFi Protect Sirens

UniFi Protect Arm Profiles

UniFi Protect Alarm Hubs

UniFi Protect Alarm Manager

UniFi Protect Relays

UniFi Protect Sensors

UniFi Protect Lights

UniFi Protect Chimes

UniFi Protect Speakers

UniFi Protect Viewers

UniFi Protect Live Views

UniFi Protect Fobs

UniFi Protect Bridges

UniFi Protect Link Stations

UniFi Protect Device Asset Files

UniFi Protect NVR & App Info

UniFi Protect Users & Identity