proxmox/docs/04-configuration/UNIFI_CONFIGURATION_STATUS.md

UniFi UDM Pro Configuration Status

Last Updated: 2025-01-20
UDM Pro IP: 192.168.0.1
Status: API Integration Configured

---

Current Configuration

API Integration Status

• API Mode: Official (read-only)
• API Key: Configured in ~/.env
• Connection: ✅ Working
• Available Endpoints: Sites endpoint only

Environment Configuration

# ~/.env
UNIFI_UDM_URL=https://192.168.0.1
UNIFI_API_MODE=official
UNIFI_API_KEY=_6WXEiH2tMDkrO3jKc54SKa53fHZE-Wg
UNIFI_SITE_ID=default
UNIFI_VERIFY_SSL=false

---

API Endpoint Availability

✅ Available (Official API)

• Sites: /proxy/network/integration/v1/sites
  • Status: Working
  • Can list sites

❌ Not Available (Official API)

• Networks/VLANs: Not available in Official API
• Devices: Not available in Official API
• Clients: Not available in Official API
• WLANs: Not available in Official API
• Events/Alarms: Not available in Official API
• System Info: Not available in Official API

Note: These endpoints require Private API mode, which needs a local admin account without 2FA/SSO.

---

Configuration Status

✅ Completed

• API integration configured
• API key authentication working
• Sites endpoint accessible
• Health check scripts created
• Utility scripts available

⏳ Unknown/Unable to Verify via API

• VLAN Configuration: Cannot query via Official API
• Network Configuration: Cannot query via Official API
• Device Status: Cannot query via Official API
• WLAN/SSID Configuration: Cannot query via Official API
• System Status: Cannot query via Official API

---

How to Check Full Configuration

Since the Official API has limited endpoints, use one of these methods:

Option 1: Web Interface (Recommended)

1. Access: https://192.168.0.1
2. Log in with your UniFi account
3. Check:
   • Settings → Networks: View all networks/VLANs
   • Settings → WiFi: View WLANs/SSIDs
   • Devices: View all devices and their status
   • Insights: View system status and statistics

Option 2: Private API Mode (Requires Local Admin Account)

1. Create a local admin account in UniFi Network app:

   • Settings → Users & Roles
   • Create new user (local account, not UniFi account)
   • Role: Administrator
   • Important: Do NOT enable 2FA/SSO

2. Update ~/.env:

   UNIFI_API_MODE=private
   UNIFI_USERNAME=<local-admin-username>
   UNIFI_PASSWORD=<password>
   

3. Use scripts to query:

   ./scripts/unifi/check-networks.sh  # List networks/VLANs
   pnpm unifi:cli networks            # List networks
   pnpm unifi:cli devices             # List devices
   

Note: Private API mode does NOT work with UniFi accounts that have 2FA/SSO enabled.

Option 3: Continue with Official API (Limited)

• Current setup works for sites endpoint
• Wait for Official API to expand endpoint coverage
• Check UniFi Network app for new endpoints as they become available

---

API Key Management

Current API Key

• Status: ✅ Working
• Type: Read-only (as configured)
• Location: ~/.env file

API Key Verification

If you need to verify or regenerate the API key:

1. Access UniFi Network app: https://192.168.0.1
2. Navigate to: Settings → Control Plane → Integrations
3. View or regenerate API keys
4. Update UNIFI_API_KEY in ~/.env if changed

Testing API Key

Test the API key directly:

curl -k -X GET 'https://192.168.0.1/proxy/network/integration/v1/sites' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Accept: application/json'

Expected response (success):

{"offset":0,"limit":25,"count":1,"totalCount":1,"data":[...]}

Expected response (invalid key):

{"error":{"code":401,"message":"Unauthorized"}}

---

Recommendations

Immediate Actions

1. ✅ API Integration: Configured and working
2. ⏳ Verify Configuration: Use web interface to check VLAN/network status
3. ⏳ Document Current Config: Manually document networks/VLANs if needed

Future Enhancements

1. Create Local Admin Account: For Private API access (if needed)
2. Monitor Official API: Check for new endpoints as UniFi expands API coverage
3. Automate Documentation: Once Private API access is available, automate config documentation

---

Related Documentation

• UNIFI_API_SETUP.md - Complete setup guide
• UNIFI_ENDPOINTS_REFERENCE.md - API endpoints reference
• scripts/unifi/README.md - Utility scripts documentation

---

Notes

• The Official API is still in development and has limited endpoints
• Private API mode provides full access but requires local admin account (no 2FA/SSO)
• Web interface remains the most reliable way to view and manage configuration
• API integration is ready for automation once more endpoints become available