Authentication

Unifly supports four authentication modes. The right choice depends on whether you need live WebSocket streams, and whether you reach the controller directly or through Ubiquiti’s cloud.

🔗Which Mode Do I Need?

flowchart TD
START["What do you need?"] --> Q0{"Direct connection
to the controller?"}
Q0 -->|"No, via Ubiquiti cloud"| CLOUD["Cloud Mode"]
Q0 -->|"Yes"| Q1{"Live event streaming
(events watch or TUI)?"}
Q1 -->|"No"| APIKEY["API Key Mode"]
Q1 -->|"Yes"| HYBRID["Hybrid Mode"]
Q1 -->|"No API key
available"| SESSION["Username/Password Mode"]

    style APIKEY fill:#50fa7b,color:#0a0a0f
    style HYBRID fill:#80ffea,color:#0a0a0f
    style SESSION fill:#f1fa8c,color:#0a0a0f
    style CLOUD fill:#ff6ac1,color:#0a0a0f

🔗API Key

Generate a key on your controller under Settings > Integrations. On UniFi OS, the same key also authenticates the Session API HTTP endpoints (/proxy/network/api/* and /proxy/network/v2/api/*), so API key mode covers CRUD, device commands, stats, DHCP reservations, admin operations, and events list.

unifly config init                     # Select "API Key" during setup
unifly --api-key <KEY> devices list    # Or pass directly

Best for: CI/CD pipelines, scripted provisioning, daily CLI automation, most everyday workflows.

🔗Username / Password

Session-based auth with cookie and CSRF token handling. Use this when you lack an Integration API key, when you need live WebSocket events, or when your controller is a classic standalone that does not accept API keys on the Session HTTP surface.

unifly config init                     # Select "Username/Password" during setup

Best for: Monitoring-focused setups where you primarily care about live event streaming.

🔗Hybrid Mode

API key for HTTP (both Integration and Session) plus username/password for the live WebSocket cookie session. The setup wizard offers this when you provide both.

unifly config init                     # Select "Hybrid" during setup

How it works: unifly uses the API key for every HTTP request and the cookie session only to establish the live WebSocket. Everything else an API key can reach is reached with the API key.

To verify Hybrid is working, run unifly events watch — if events stream, the WebSocket cookie session is active.

🔗Cloud Mode

Cloud mode reaches your controllers through Ubiquiti’s Site Manager instead of a direct network connection. It needs two things: a Site Manager API key (created under your Ubiquiti account, not on the controller) and a console ID (host_id) naming which console to talk to.

unifly config cloud-setup              # Guided setup: validates the key,
                                       # picks a console and site, writes the profile

Two distinct surfaces run on this key:

• Fleet queries (unifly cloud hosts|sites|devices|isp|sdwan) talk to the Site Manager fleet API directly and need no host_id at all.
• Connector-routed commands: with auth_mode = "cloud", regular Integration-backed commands (networks list, wifi create, firewall policies list, …) tunnel through the cloud connector to the console named by host_id. When the API key sees exactly one console (or exactly one you own), unifly resolves host_id automatically; otherwise set it in the profile or pass --host-id.

Session-backed commands (events watch, stats, device commands, admin) are not reachable through the connector and still require direct controller access. The full walkthrough lives on the Cloud & Site Manager page.

🔗Credential Storage

Credentials go in your OS keyring by default:

The config.toml file stores non-sensitive settings like controller URLs and site names. The setup wizard offers keyring storage by default, but also provides a plaintext config fallback for environments where the keyring isn’t available (headless servers, WSL, CI).

Secrets resolve in a fixed order: an environment variable named by api_key_env (or UNIFI_PASSWORD for passwords), then an explicit api_key = "..." / password = "..." value in config.toml, then the keyring. Explicit config beats the keyring, so editing a plaintext value in config.toml is never silently overridden by a stale keyring entry from an earlier config init.

To update a stored password:

unifly config set-password              # Updates the active profile
unifly config set-password --profile office  # Updates a specific profile

🔗Environment Variables

For CI/CD and scripting, pass credentials via environment:

export UNIFI_API_KEY="your-api-key-here"
export UNIFI_URL="https://192.168.1.1"
unifly devices list

graph LR
A["CLI Flags"] -->|highest| RESULT["Final Value"]
B["Environment Variables"] -->|medium| RESULT
C["Config File"] -->|lowest| RESULT

    style A fill:#ff6ac1,color:#0a0a0f
    style B fill:#f1fa8c,color:#0a0a0f
    style C fill:#80ffea,color:#0a0a0f

CLI flags override environment variables, which override config file values.

🔗MFA / TOTP

If your controller requires two-factor authentication:

# One-shot with 1Password CLI
UNIFI_TOTP=$(op read "op://Personal/UniFi/one-time password") \
  unifly devices list

# Or set totp_env in your config.toml profile:
# [profiles.home]
# totp_env = "UNIFI_TOTP"

🔗Next Steps

• Configuration: full profile reference, environment variables, and precedence rules
• CLI Commands: what you can do with each auth mode
• Troubleshooting: common auth errors and fixes