unifi-connect

UniFi Connect

The first thing to know: SSH is usually closed and you do not need it. UniFi OS exposes a full REST API on the same host as the web UI, and everything these skills do goes through it. The second thing: UniFi has three overlapping API surfaces with different auth rules, and picking the wrong one produces errors that look like broken credentials when they are not.

Throughout, <UDM_HOST> is your gateway's LAN address. Never hardcode it into a file you might share.

Lane 1: API key (use this)

API keys are the modern lane. No login round-trip, no cookie jar, no CSRF token, and they sidestep the HTTP/2 bug described below.

Minting a key over the API

The admin UI has a key page, but you do not need it. Keys are mintable from an authenticated session:

# Log in once to get a session
curl -sk -X POST "https://<UDM_HOST>/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"<ADMIN_USER>","password":"<ADMIN_PASS>"}' \
  -c /tmp/unifi_cookies -D /tmp/unifi_headers

CSRF=$(grep -i 'x-updated-csrf-token' /tmp/unifi_headers | awk '{print $2}' | tr -d '\r')

# Mint a named key
curl -sk --http1.1 -b /tmp/unifi_cookies -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -X POST "https://<UDM_HOST>/proxy/users/api/v2/user/self/keys" \
  -d '{"name":"agent"}'

The response contains the key once. Store it and move on. Give the agent its own named key rather than sharing yours: named keys are individually revocable, and when something writes a policy you did not expect you want to know which identity did it.

The same path answers GET, which lists existing keys with id, name, masked_api_key, timestamps, and the key's permissions map. Useful for confirming a key exists without minting another, and for auditing what is out there:

curl -sk -H "X-API-Key: $UNIFI_API_KEY" \
  "https://<UDM_HOST>/proxy/users/api/v2/user/self/keys"

Read that permissions map once. A key minted by an admin account inherits that account's rights across every UniFi application on the box, Network and Protect and the rest, not just the one you meant to automate. There is no "read-only Network" key by default. So: create a dedicated limited admin account and mint the key as that account rather than as your own super-admin, and treat the key as equivalent to the password of whoever minted it.