proxmox/docs/04-configuration/UDM_PRO_API_LIMITATIONS.md

UDM Pro API Limitations and Configuration

Last Updated: 2025-01-20
Status: API write access limitations documented

---

Summary

The UDM Pro configuration via API has significant limitations:

1. Official API (API Key): Read access to many endpoints, write access limited to ACL Rules, Firewall Zones, Traffic Matching Lists
2. Private API (Username/Password): Requires local admin account without 2FA/SSO
3. Network/VLAN Creation: Not available via Official API (read-only for networks)
4. DHCP Reservations/Port Profiles: Not available via Official API (requires web UI)

---

API Mode Comparison

Official API Mode

Authentication: API Key only (no username/password)
Base URL: https://192.168.0.1/proxy/network/integration/v1/
Location: Local UDM Pro (192.168.0.1)

Endpoints Available (Read Access):

• ✅ /sites - List sites
• ✅ /sites/{siteId}/networks - List networks/VLANs
• ✅ /sites/{siteId}/networks/{networkId} - Get network details
• ✅ /sites/{siteId}/devices - List devices
• ✅ /sites/{siteId}/clients - List clients
• ✅ /sites/{siteId}/acl-rules - List ACL/firewall rules
• ✅ /sites/{siteId}/firewall/zones - List firewall zones
• ✅ /sites/{siteId}/traffic-matching-lists - List traffic matching lists
• ✅ /sites/{siteId}/wans - List WAN interfaces
• ✅ /info - Application information

Endpoints Available (Write Access):

• ✅ /sites/{siteId}/acl-rules - Create/update/delete ACL rules (with limitations)
• ✅ /sites/{siteId}/firewall/zones - Create/update/delete firewall zones
• ✅ /sites/{siteId}/traffic-matching-lists - Create/update/delete traffic matching lists

Endpoints NOT Available:

• ❌ Network/VLAN creation (read-only for networks)
• ❌ Network/VLAN modification (read-only for networks)
• ❌ DHCP reservations (/dhcp-reservations - 404 NOT_FOUND)
• ❌ Port profiles (/port-profiles - 404 NOT_FOUND)
• ❌ System configuration (hostname, timezone, NTP, backups)
• ❌ Individual WAN details (/wans/{wanId} - 404 NOT_FOUND)

Current API Key: _6WXEiH2tMDkrO3jKc54SKa53fHZE-Wg
Status: ✅ Working (read access confirmed, write access for ACL Rules/Firewall Zones/Traffic Matching Lists)

Known Limitations:

• Cannot create ACL rules blocking overlapping source/destination networks
• Network creation/modification not supported
• DHCP reservations require web UI
• Port profiles require web UI

Private API Mode

Authentication: Username/Password (cookie-based session)
Endpoints Available:

• ✅ Read networks/VLANs
• ✅ Read devices
• ✅ Read clients
• ✅ Read system info
• ❌ Create/modify networks (403 Forbidden - permission issue)

Account Status:

• unifi_api: ✅ Read access working, ❌ Write access blocked (403)
• nsatoshi2007: ❌ Authentication failed

Requirements:

• Local admin account (not SSO/cloud account)
• No 2FA enabled
• Full network management permissions

---

Current Configuration

Environment Variables (~/.env)

UNIFI_UDM_URL=https://192.168.0.1
UNIFI_API_MODE=official
UNIFI_API_KEY=_6WXEiH2tMDkrO3jKc54SKa53fHZE-Wg
UNIFI_USERNAME=nsatoshi2007
UNIFI_PASSWORD="L@kers2010$$"
UNIFI_SITE_ID=default
UNIFI_VERIFY_SSL=false

Current Status

• Official API: ✅ Working (read access to 10+ endpoints, write access for ACL Rules/Firewall Zones/Traffic Matching Lists)
• Private API (unifi_api): ✅ Read access, ❌ Write access blocked (403)
• Private API (nsatoshi2007): ❌ Authentication failed (2FA/SSO incompatible)

---

Solutions for Network Configuration

Option 1: Manual Configuration (Recommended)

Use the UniFi Network web interface to configure VLANs:

1. Access: https://192.168.0.1
2. Follow: UDM_PRO_COMPLETE_MANUAL_GUIDE.md

Pros:

• Full access to all features
• No permission issues
• Visual interface

Cons:

• Manual process
• Time-consuming for many VLANs

Option 2: Create Local Admin with Write Permissions

1. Access UniFi Network web UI
2. Navigate to Settings → System Settings → Users
3. Create a new local admin account:
   • Username: (choose a name)
   • Password: (choose a strong password)
   • Role: Full Admin / Network Admin
   • Important: Ensure it's a local account (not SSO)
   • Important: Do NOT enable 2FA
4. Update ~/.env:

   UNIFI_API_MODE=private
   UNIFI_USERNAME=<new-username>
   UNIFI_PASSWORD="<new-password>"
   

5. Test network creation via API

Pros:

• Automated configuration possible
• Scriptable

Cons:

• Requires account creation
• Must ensure proper permissions

Option 3: Grant Write Permissions to Existing Account

If you have an existing local admin account:

1. Access UniFi Network web UI
2. Navigate to Settings → System Settings → Users
3. Edit the account (e.g., unifi_api)
4. Verify/update role to include network management permissions
5. Ensure account is local (not SSO)
6. Ensure 2FA is disabled
7. Test network creation

Pros:

• Uses existing account
• Automated configuration possible

Cons:

• May require permission changes
• Must verify account type

---

Troubleshooting Authentication

Private API Authentication Fails

Symptoms:

• 403 Forbidden or 401 Unauthorized
• "Invalid username or password"
• "2fa token required"

Possible Causes:

1. Account doesn't exist locally
2. Wrong password
3. Account is SSO/cloud-only (not local)
4. 2FA is enabled (Private API doesn't support 2FA)
5. Account is disabled

Solutions:

1. Verify account exists and is local
2. Reset password
3. Create new local admin account
4. Disable 2FA if enabled
5. Check account status in web UI

Write Access Blocked (403 Forbidden)

Symptoms:

• Read access works (can list networks, devices)
• Write access fails (cannot create/modify)

Possible Causes:

1. Insufficient permissions/role
2. Account role doesn't include network management
3. API endpoint requires different permissions

Solutions:

1. Check user role in Settings → System Settings → Users
2. Update role to include network management permissions
3. Verify account has "Full Admin" or "Network Admin" role
4. Try creating networks via web UI to verify account permissions

---

Verification

Test Official API (Read-Only)

cd /home/intlc/projects/proxmox
export UNIFI_API_MODE=official
pnpm --filter unifi-api exec node dist/cli/index.js sites

Test Private API (Read Access)

cd /home/intlc/projects/proxmox
export UNIFI_API_MODE=private
pnpm --filter unifi-api exec node dist/cli/index.js networks

Test Private API (Write Access)

cd /home/intlc/projects/proxmox
NODE_TLS_REJECT_UNAUTHORIZED=0 node scripts/unifi/configure-vlans-node.js

---

Related Documentation

• UDM_PRO_STATUS.md - Configuration status
• UDM_PRO_CONFIGURATION_CHECKLIST.md - Complete configuration checklist
• UNIFI_API_SETUP.md - API setup guide
• UNIFI_CONFIGURATION_STATUS.md - Current configuration status

---

Last Updated: 2025-01-20