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

```bash
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](./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`:
   ```bash
   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)

```bash
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)

```bash
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)

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

---

## Related Documentation

- [UDM_PRO_STATUS.md](./UDM_PRO_STATUS.md) - Configuration status
- [UDM_PRO_CONFIGURATION_CHECKLIST.md](./UDM_PRO_CONFIGURATION_CHECKLIST.md) - Complete configuration checklist
- [UNIFI_API_SETUP.md](./UNIFI_API_SETUP.md) - API setup guide
- [UNIFI_CONFIGURATION_STATUS.md](./UNIFI_CONFIGURATION_STATUS.md) - Current configuration status

---

**Last Updated:** 2025-01-20