proxmox/docs/04-configuration/UDM_PRO_API_ACCESS_TEST_RESULTS.md

UDM Pro API Access Test Results

Last Updated: 2025-01-20
Status: Active Documentation API Key: _6WXEiH2tMDkrO3jKc54SKa53fHZE-Wg
Site ID: 88f7af54-98f8-306a-a1c7-c9349722b1f6
Test Date: 2025-01-20

---

Overview

This document contains test results for the Official UniFi Network API (v1 integration endpoints) using the local API key. Tests were performed to identify available endpoints, access levels (read/write), and limitations.

Important: All API calls are made to the local UDM Pro at 192.168.0.1. This is not the cloud-based Site Manager API. All limitations documented here are specific to the local Official UniFi Network API.

Base URL: https://192.168.0.1/proxy/network/integration/v1/

---

Test Results Summary

✅ Available Endpoints (Read Access)

Endpoint	Method	Status	Description
/sites	GET	✅ Working	List all sites
/sites/{siteId}/networks	GET	✅ Working	List networks/VLANs
/sites/{siteId}/networks/{networkId}	GET	✅ Working	Get network details
/sites/{siteId}/devices	GET	✅ Working	List devices
/sites/{siteId}/clients	GET	✅ Working	List clients
/sites/{siteId}/acl-rules	GET	✅ Working	List ACL/firewall rules
/sites/{siteId}/firewall/zones	GET	✅ Working	List firewall zones
/sites/{siteId}/traffic-matching-lists	GET	✅ Working	List traffic matching lists
/sites/{siteId}/wans	GET	✅ Working	List WAN interfaces
/info	GET	✅ Working	Application information

✅ Available Endpoints (Write Access - Confirmed)

Endpoint	Method	Status	Description
/sites/{siteId}/acl-rules	POST/PUT/DELETE	✅ Working	Create/update/delete ACL rules
/sites/{siteId}/firewall/zones	POST/PUT/DELETE	✅ Working	Create/update/delete firewall zones
/sites/{siteId}/traffic-matching-lists	POST/PUT/DELETE	✅ Working	Create/update/delete traffic matching lists

❌ Unavailable Endpoints

Endpoint	Method	Status	Expected Error
/sites/{siteId}/dhcp-reservations	GET	❌ 404 NOT_FOUND	DHCP reservations not available
/sites/{siteId}/port-profiles	GET	❌ 404 NOT_FOUND	Port profiles not available
/sites/{siteId}/wans/{wanId}	GET	❌ 404 NOT_FOUND	Individual WAN details not available

---

Detailed Test Results

1. Sites Endpoint

Endpoint: GET /proxy/network/integration/v1/sites

Result: ✅ Working

Response:

{
    "offset": 0,
    "limit": 25,
    "count": 1,
    "totalCount": 1,
    "data": [
        {
            "id": "88f7af54-98f8-306a-a1c7-c9349722b1f6",
            "internalReference": "default",
            "name": "Default"
        }
    ]
}

---

2. Networks Endpoint

Endpoint: GET /proxy/network/integration/v1/sites/{siteId}/networks

Result: ✅ Working

Response: Returns list of all networks/VLANs (19 networks - 18 VLANs + 1 default network)

Access Level: Read access confirmed

---

3. ACL Rules Endpoint

Endpoint: GET /proxy/network/integration/v1/sites/{siteId}/acl-rules

Result: ✅ Working

Response: Returns list of ACL/firewall rules (4 rules confirmed)

Access Level: Read and Write access confirmed (POST/PUT/DELETE available)

---

4. Devices Endpoint

Endpoint: GET /proxy/network/integration/v1/sites/{siteId}/devices

Result: ✅ Working

Response: Returns list of devices (1 device confirmed - UDM Pro)

Access Level: Read access confirmed

---

5. Clients Endpoint

Endpoint: GET /proxy/network/integration/v1/sites/{siteId}/clients

Result: ✅ Working

Response: Returns list of active clients

Access Level: Read access confirmed

---

6. WANs Endpoint

Endpoint: GET /proxy/network/integration/v1/sites/{siteId}/wans

Result: ✅ Working

Response: Returns list of WAN interfaces (2 WANs - Internet 1, Internet 2)

Access Level: Read access confirmed

Note: Individual WAN details endpoint (/wans/{wanId}) returns 404 NOT_FOUND

---

7. Firewall Zones Endpoint

Endpoint: GET /proxy/network/integration/v1/sites/{siteId}/firewall/zones

Result: ✅ Working

Response: Returns list of firewall zones

Access Level: Read and Write access confirmed (POST/PUT/DELETE available)

---

8. Traffic Matching Lists Endpoint

Endpoint: GET /proxy/network/integration/v1/sites/{siteId}/traffic-matching-lists

Result: ✅ Working

Response: Returns list of traffic matching lists

Access Level: Read and Write access confirmed (POST/PUT/DELETE available)

---

9. Application Info Endpoint

Endpoint: GET /proxy/network/integration/v1/info

Result: ✅ Working

Response:

{
    "applicationVersion": "10.0.162"
}

---

10. DHCP Reservations Endpoint

Endpoint: GET /proxy/network/integration/v1/sites/{siteId}/dhcp-reservations

Result: ❌ NOT AVAILABLE

Error: 404 NOT_FOUND - "No endpoint GET /integration/v1/sites/{siteId}/dhcp-reservations"

Conclusion: DHCP static IP reservations are not available via the Official API

---

11. Port Profiles Endpoint

Endpoint: GET /proxy/network/integration/v1/sites/{siteId}/port-profiles

Result: ❌ NOT AVAILABLE

Error: 404 NOT_FOUND

Conclusion: Port profiles are not available via the Official API

---

API Limitations Summary

Read-Only Limitations

The following configuration items cannot be read or modified via the Official API:

1. DHCP Static IP Reservations

   • Not available via API
   • Requires manual configuration via web UI

2. Port Profiles

   • Not available via API
   • Requires manual configuration via web UI

3. Individual WAN Details

   • List endpoint works, but individual WAN details endpoint returns 404
   • WAN configuration may require web UI

Write Access Limitations

While many endpoints support write operations (POST/PUT/DELETE), the following limitations apply:

1. Network Creation/Modification

   • Read access confirmed
   • Write access not tested (may require specific permissions)

2. ACL Rules Limitations

   • Write access confirmed
   • Known limitation: Cannot create rules blocking overlapping source/destination networks
   • See UDM_PRO_FIREWALL_API_LIMITATIONS.md for details

3. System Settings

   • Not available via API (hostname, timezone, NTP, backups)
   • Requires manual configuration via web UI

---

Access Level Summary

Full Read/Write Access ✅

• ACL Rules (with limitations)
• Firewall Zones
• Traffic Matching Lists

Read-Only Access ✅

• Sites
• Networks/VLANs
• Devices
• Clients
• WANs (list only)

No Access ❌

• DHCP Reservations
• Port Profiles
• System Settings
• Individual WAN Details

---

Comparison with Previous API Key

Previous API Key: W01fuZ_tdN6NdpknSetrdcOAra2moezk (sankofa)

New API Key: _6WXEiH2tMDkrO3jKc54SKa53fHZE-Wg

Results: ✅ Access levels appear identical - no changes in available endpoints or permissions detected.

---

Recommendations

1. Use API for:

   • Reading network/VLAN configuration
   • Reading device and client information
   • Creating/updating firewall rules (ACL rules)
   • Creating firewall zones and traffic matching lists

2. Use Web UI for:

   • DHCP static IP reservations
   • Port profiles configuration
   • System settings (hostname, timezone, NTP, backups)
   • WAN configuration (detailed settings)

3. Documentation:

   • See UDM_PRO_API_LIMITATIONS.md for general API limitations
   • See UDM_PRO_FIREWALL_API_LIMITATIONS.md for firewall-specific limitations
   • See UDM_PRO_STATUS.md for current configuration status

---

Related Documentation

• UDM_PRO_API_LIMITATIONS.md - General API limitations
• UDM_PRO_FIREWALL_API_LIMITATIONS.md - Firewall API limitations
• UDM_PRO_API_FIREWALL_ENDPOINTS.md - Firewall API endpoints documentation
• UDM_PRO_STATUS.md - Configuration status

---

Last Updated: 2025-01-20