Authentication

Unifly supports three authentication modes. The right choice depends on whether you need live WebSocket streams.

🔗Which Mode Do I Need?

flowchart TD
START["What do you need?"] --> 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

🔗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.

🔗Credential Storage

All credentials are stored in your OS keyring:

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).

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