Configuration
Back to Home
The unifi package uses a layered configuration system to resolve UniFi controller credentials. Settings can come from a config file, environment variables, or explicit flags, with a clear priority order.
Resolution Priority
Configuration is resolved in this order, with later sources overriding earlier ones:
1. Config file (~/.core/config.yaml) ← lowest priority
2. Environment variables ← overrides config file
3. Flag/argument overrides ← highest priority
Config File
Location: ~/.core/config.yaml
unifi:
url: "https://10.69.1.1"
user: "admin"
pass: "password"
apikey: ""
insecure: true
Config Keys
| Key | Type | Description |
|---|---|---|
unifi.url |
string | Controller URL |
unifi.user |
string | Username |
unifi.pass |
string | Password |
unifi.apikey |
string | API key (alternative to user/pass) |
unifi.insecure |
bool | Skip TLS certificate verification |
Environment Variables
| Variable | Config Key | Description |
|---|---|---|
UNIFI_URL |
unifi.url |
Controller URL |
UNIFI_USER |
unifi.user |
Username |
UNIFI_PASS |
unifi.pass |
Password |
UNIFI_APIKEY |
unifi.apikey |
API key |
UNIFI_INSECURE |
unifi.insecure |
Set to "true" or "1" to skip TLS verification |
export UNIFI_URL="https://192.168.1.1"
export UNIFI_USER="admin"
export UNIFI_PASS="secret"
export UNIFI_INSECURE="true"
Default Values
| Setting | Default |
|---|---|
| URL | https://10.69.1.1 |
| User | (empty) |
| Pass | (empty) |
| API Key | (empty) |
| Insecure | false |
If no URL is configured from any source, it defaults to https://10.69.1.1.
API
ResolveConfig
func ResolveConfig(flagURL, flagUser, flagPass, flagAPIKey string, flagInsecure *bool) (url, user, pass, apikey string, insecure bool, err error)
Resolves the complete configuration from all sources. Returns the final resolved values. Pass empty strings and nil for flags you do not wish to override.
url, user, pass, apikey, insecure, err := unifi.ResolveConfig(
"", // No URL override
"", // No user override
"", // No pass override
"", // No API key override
nil, // No insecure override
)
NewFromConfig
func NewFromConfig(flagURL, flagUser, flagPass, flagAPIKey string, flagInsecure *bool) (*Client, error)
Calls ResolveConfig internally, validates that at least one authentication method is configured (user/pass or API key), and creates a connected client.
// Use defaults from config file and env
client, err := unifi.NewFromConfig("", "", "", "", nil)
// Override just the URL via flag
client, err := unifi.NewFromConfig("https://unifi.local:8443", "", "", "", nil)
If neither a user/pass pair nor an API key is resolved, NewFromConfig returns an error with a helpful message:
no credentials configured (set UNIFI_USER/UNIFI_PASS or UNIFI_APIKEY, or run: core unifi config)
SaveConfig
func SaveConfig(url, user, pass, apikey string, insecure *bool) error
Persists settings to the config file (~/.core/config.yaml). Only non-empty values are saved. This is used by the core unifi config CLI command.
// Save URL and credentials
insecure := true
err := unifi.SaveConfig(
"https://10.69.1.1",
"admin",
"my-password",
"",
&insecure,
)
Authentication Methods
The UniFi controller supports two authentication methods:
Username/Password
Traditional authentication with a local admin account. Set unifi.user and unifi.pass.
API Key
Token-based authentication available on newer UniFi OS controllers. Set unifi.apikey. When an API key is provided, it takes precedence over username/password for authentication at the SDK level.
Examples
Environment-Only Setup
# Set credentials via environment
export UNIFI_URL="https://unifi.office.local"
export UNIFI_APIKEY="my-api-key-here"
export UNIFI_INSECURE="true"
// Client picks up environment automatically
client, err := unifi.NewFromConfig("", "", "", "", nil)
Config File + Environment Override
# ~/.core/config.yaml — base config
unifi:
url: "https://10.69.1.1"
user: "admin"
pass: "default-password"
# Override password for a specific session
export UNIFI_PASS="session-specific-password"
CLI Flag Override
// Highest priority — CLI flags override everything
flagURL := "https://192.168.1.1"
insecure := true
client, err := unifi.NewFromConfig(flagURL, "admin", "pass", "", &insecure)
See Also
- Home — Package overview and quick start
- UniFi-Client — Detailed client API and usage examples