# Omada Controller Connection Guide

**Last Updated:** 2025-01-20  
**Status:** Connection Troubleshooting

---

## Current Status

✅ **Controller Reachable**: `https://192.168.11.8:8043` (HTTP 200 response)  
❌ **API Authentication**: Failing - Invalid credentials  
⚠️ **Issue**: API_KEY/API_SECRET cannot be used for `/api/v2/login` endpoint

---

## Connection Options

### Option 1: Web Interface Access (Recommended for Initial Setup)

Access the Omada Controller web interface directly:

```
URL: https://192.168.11.8:8043
```

**Note**: You'll need to accept the self-signed SSL certificate if using a browser.

**From the web interface, you can:**
- View all devices (routers, switches, APs)
- Check device adoption status
- View VLAN configurations
- Configure network settings
- Export configurations

### Option 2: API Access with Admin Credentials

The `/api/v2/login` endpoint requires **admin username and password**, not OAuth credentials.

**Update `~/.env` with admin credentials:**

```bash
# Omada Controller Configuration - Admin Credentials
OMADA_CONTROLLER_URL=https://192.168.11.8:8043
OMADA_ADMIN_USERNAME=your-admin-username
OMADA_ADMIN_PASSWORD=your-admin-password
OMADA_SITE_ID=090862bebcb1997bb263eea9364957fe
OMADA_VERIFY_SSL=false
```

**Then test connection:**

```bash
cd /home/intlc/projects/proxmox
node test-omada-direct.js
```

### Option 3: OAuth Token Endpoint (If Available)

If your Omada Controller supports OAuth token endpoint:

1. **Check OAuth Configuration**:
   - Access Omada Controller web interface
   - Navigate to: **Settings** → **Platform Integration** → **Open API**
   - Check if OAuth application supports "Client Credentials" mode

2. **If Client Credentials Mode Available**:
   - Change OAuth app from "Authorization Code" to "Client Credentials"
   - Use Client ID/Secret with OAuth token endpoint
   - Update authentication code to use OAuth endpoint

3. **Find OAuth Token Endpoint**:
   - Check Omada Controller API documentation
   - Typically: `/api/v2/oauth/token` or similar

---

## Testing Connection

### Test Scripts Available

1. **Direct Connection Test** (uses Node.js https module):
   ```bash
   node test-omada-direct.js
   ```
   - Uses admin username/password from `~/.env`
   - Better SSL handling
   - Lists devices and VLANs on success

2. **API Library Test** (uses omada-api library):
   ```bash
   node test-omada-connection.js
   ```
   - Currently failing due to fetch SSL issues
   - Should work once authentication is fixed

### Manual API Test (curl)

```bash
# Test login endpoint
curl -k -X POST https://192.168.11.8:8043/api/v2/login \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_ADMIN_USERNAME","password":"YOUR_ADMIN_PASSWORD"}'
```

**Expected Response:**
```json
{
  "errorCode": 0,
  "result": {
    "token": "your-token-here",
    "expiresIn": 3600
  }
}
```

---

## Current Configuration

### Environment Variables (Current)

```bash
OMADA_CONTROLLER_URL=https://192.168.11.8:8043
OMADA_API_KEY=273615420c01452a8a2fd2e00a177eda
OMADA_API_SECRET=8d3dc336675e4b04ad9c1614a5b939cc
OMADA_SITE_ID=090862bebcb1997bb263eea9364957fe
OMADA_VERIFY_SSL=false
```

**Note**: `OMADA_API_KEY` and `OMADA_API_SECRET` are OAuth credentials, not admin credentials.

### Controller Information

- **URL**: `https://192.168.11.8:8043`
- **Site ID**: `090862bebcb1997bb263eea9364957fe`
- **Status**: Controller is reachable (HTTP 200)
- **SSL**: Self-signed certificate (verification disabled)

---

## Next Steps

### Immediate Actions

1. **Access Web Interface**:
   - Open `https://192.168.11.8:8043` in browser
   - Accept SSL certificate warning
   - Log in with admin credentials
   - Verify device inventory

2. **Update Credentials**:
   - Add `OMADA_ADMIN_USERNAME` and `OMADA_ADMIN_PASSWORD` to `~/.env`
   - Or update existing `OMADA_API_KEY`/`OMADA_API_SECRET` if they are actually admin credentials

3. **Test API Connection**:
   ```bash
   node test-omada-direct.js
   ```

### Verify Device Inventory

Once connected, verify:

- **Routers**: ER605-A, ER605-B (if deployed)
- **Switches**: ES216G-1, ES216G-2, ES216G-3
- **Device Status**: Online/Offline
- **Adoption Status**: Adopted/Pending
- **Firmware Versions**: Current versions

### Verify Configuration

- **VLANs**: List all configured VLANs
- **Network Settings**: Current network configuration
- **Device IPs**: Actual IP addresses of devices

---

## Troubleshooting

### Connection Issues

**Problem**: Cannot connect to controller

**Solutions**:
- Verify controller IP: `ping 192.168.11.8`
- Check firewall: Ensure port 8043 is accessible
- Test HTTPS: `curl -k -I https://192.168.11.8:8043`
- Verify controller service is running

### Authentication Issues

**Problem**: "Invalid username or password"

**Solutions**:
- Verify admin credentials are correct
- Check if account is locked or disabled
- Try logging in via web interface first
- Reset admin password if needed

**Problem**: "OAuth authentication failed"

**Solutions**:
- Use admin credentials instead of OAuth credentials
- Check OAuth application configuration in controller
- Verify Client Credentials mode is enabled (if using OAuth)

### SSL Certificate Issues

**Problem**: SSL certificate errors

**Solutions**:
- For testing: Set `OMADA_VERIFY_SSL=false` in `~/.env`
- For production: Install valid SSL certificate on controller
- Accept certificate in browser when accessing web interface

---

## API Endpoints Reference

### Authentication

- **POST** `/api/v2/login`
  - Body: `{"username": "admin", "password": "password"}`
  - Returns: `{"errorCode": 0, "result": {"token": "...", "expiresIn": 3600}}`

### Sites

- **GET** `/api/v2/sites`
  - Headers: `Authorization: Bearer <token>`
  - Returns: List of sites

### Devices

- **GET** `/api/v2/sites/{siteId}/devices`
  - Headers: `Authorization: Bearer <token>`
  - Returns: List of devices (routers, switches, APs)

### VLANs

- **GET** `/api/v2/sites/{siteId}/vlans`
  - Headers: `Authorization: Bearer <token>`
  - Returns: List of VLANs

---

## Related Documentation

- **[OMADA_HARDWARE_CONFIGURATION_REVIEW.md](OMADA_HARDWARE_CONFIGURATION_REVIEW.md)** - Hardware and configuration review
- **[OMADA_API_SETUP.md](OMADA_API_SETUP.md)** - API integration setup
- **[ER605_ROUTER_CONFIGURATION.md](ER605_ROUTER_CONFIGURATION.md)** - Router configuration guide
- **[OMADA_AUTH_NOTE.md](/docs/11-references/OMADA_AUTH_NOTE.md)** - Authentication notes

---

**Document Status:** Active  
**Maintained By:** Infrastructure Team  
**Last Updated:** 2025-01-20