> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neoagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting UniFi to Neo

> Save your UniFi Site Manager API key in Neo, and decide what each agent can do

You connect UniFi once at the MSP level, then turn it on per agent. Setup takes a few minutes.

<Info>
  UniFi uses a single Site Manager API key per MSP. Save it once and every agent that has UniFi permissions can use it.
</Info>

## 1. Create an API key in UniFi Site Manager

<Steps>
  <Step title="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.
  </Step>

  <Step title="Create the key">
    Open **Settings → API Keys** and click **Create New API Key**.

    <Tip>
      Copy the key somewhere safe once it's generated — UniFi shows it only once.
    </Tip>
  </Step>
</Steps>

## 2. Add the credentials in Neo

<Steps>
  <Step title="Open Integrations">
    In the Neo Dashboard, open **Integrations** and find the **Ubiquiti UniFi** card under **Networking**.
  </Step>

  <Step title="Save the API key">
    Paste the key and click **Save**. Neo checks it against Site Manager before storing it.
  </Step>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="Read Only" icon="magnifying-glass">
    Every area set to read only. The agent can look up consoles, sites, devices, clients, networks and firewall rules, but never makes changes.
  </Card>

  <Card title="Helpdesk" icon="headset">
    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.
  </Card>

  <Card title="IT Admin" icon="user-shield">
    Every writable area read and write, but every write waits on a technician. A cautious rollout tier.
  </Card>

  <Card title="Full Automation" icon="bolt">
    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.
  </Card>
</CardGroup>

### Or set each area by hand

| Area                 | Access levels you can pick          | Notes                                                                                                                 |
| -------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Consoles & Sites** | Disabled, Read Only                 | Consoles, sites, fleet-wide device inventory, ISP health, SD-WAN. Read only by API design.                            |
| **Devices**          | Disabled, Read Only, Read and Write | Adopted and pending devices, statistics, restart, PoE power-cycle, adopt/unadopt. Writes always wait on a technician. |
| **Clients**          | Disabled, Read Only, Read and Write | Connected clients and guest authorization. Writes always wait on a technician.                                        |
| **Networks & WiFi**  | Disabled, Read Only, Read and Write | Networks/VLANs, SSIDs, WANs, VPNs, RADIUS, switching, DNS policies. Writes always wait on a technician.               |
| **Firewall & ACLs**  | Disabled, Read Only, Read and Write | Firewall policies and zones, ACL rules, traffic matching lists. Writes always wait on a technician.                   |
| **Hotspot Vouchers** | Disabled, Read Only, Read and Write | Guest hotspot vouchers. Deleting always waits on a technician; issuing follows the group setting.                     |

## 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.** Site Manager's cloud API exposes no write for it.
* **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.** Each UniFi site is matched to a PSA company by name during each PSA metadata sync; review or fix matches on the card's **Organization Mapping** tab.
* **Rate limiting.** Neo paces calls to Ubiquiti's limit of 100 requests per minute per console.

## If UniFi refuses Neo's requests

| What the error says                    | Cause                                                                                                                        | Fix                                                                                                                           |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`                     | The API key was deleted at unifi.ui.com, or the UI account that created it lost access                                       | Create a new API key and save it in Neo                                                                                       |
| `403 forbidden: host not found`        | The console is not one this key's account can manage                                                                         | Give the UI account admin access to that console in Site Manager, or create the key from an account that has it               |
| `408 DeviceTimeout` on a console path  | The console is offline, or it is a self-hosted UniFi Network Server — Ubiquiti's Connector only proxies to UniFi OS consoles | Cloud-level data (consoles, sites, devices, ISP health) still works for that server; per-site detail needs a UniFi OS console |
| `404 device_offline` on a console path | The console is known to Site Manager but not connected to the cloud right now                                                | Bring the console back online; cloud-level data still works meanwhile                                                         |
| `404` on a console path                | The console's firmware or Network application is older than the endpoint (the Connector needs UniFi OS 5.0.3 or newer)       | Update the console                                                                                                            |

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

## Security

* The API key lives in Azure Key Vault. It is never stored in plaintext.
* All traffic goes over HTTPS to `api.ui.com`; per-console calls are proxied by Ubiquiti's cloud Connector, so Neo never connects to a console directly.
* 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.