Omada Open API — CTRL-COMISARIATO, resuelto: IP directa, no el conector cloud

CTRL-COMISARIATO es un controlador SDN Omada embebido en un router (dueño tic@conkafecito.com), administrado normalmente desde el portal Omada Cloud (omada.tplinkcloud.com) — distinto de un “Cloud-Based Controller” real (una instancia SaaS de Omada). Credenciales de la Open API (modo Client) en Infisical: OMADA_CTRL_COMISARIATO_CLIENT_ID, OMADA_CTRL_COMISARIATO_CLIENT_SECRET, OMADA_CTRL_COMISARIATO_OMADAC_ID, OMADA_CTRL_COMISARIATO_DEVICE_ID. App Claude-estebN en Integración de plataforma → API abierta, Rol Administrator, todos los sitios.

El callejón sin salida: el conector cloud no sirve para este tipo de controlador

POST https://use1-api-omada-controller-connector.tplinkcloud.com/openapi/authorize/token?grant_type=client_credentials devuelve siempre {"errorCode":-1200,"msg":"You have been logged out of the controller..."}, sin importar la convención de nombres de campo (client_id/clientId). No es un problema de permisos ni de credenciales — es que el conector cloud de tplinkcloud.com no expone la Open API para controladores embebidos en router (a diferencia de un Cloud-Based Controller real). Confirmado con foros de TP-Link y con la documentación de integraciones de terceros (ej. Home Assistant): controladores de este tipo — TP-Link los llama “Fusion Gateway” en ese contexto — necesitan llamar la Open API directo contra la IP del propio router, no a través del proxy cloud.

La solución: IP directa, puerto 443 (no 8043)

El patrón documentado para controladores software/OC200 usa el puerto 8043 (https://<ip>:8043/openapi/...), pero un controlador embebido en el firmware del router sirve la Open API en el puerto de administración estándar del router, 443 — 8043 da Connection refused ahí. Verificado end-to-end el 2026-08-16 contra https://10.10.20.1/openapi/... (la IP del router en la vSwitch de sr250, alcanzable desde vm-playground vía NetBird gracias a vm-dev como routing peer de 10.10.20.0/24 — ver NetBird):

curl -sk -X POST "https://10.10.20.1/openapi/authorize/token?grant_type=client_credentials" \
  -H "Content-Type: application/json" \
  -d '{"omadacId":"<OMADAC_ID>","client_id":"<CLIENT_ID>","client_secret":"<CLIENT_SECRET>"}'
# {"errorCode":0,"msg":"Open API Get Access Token successfully.","result":{"accessToken":"AT-...","tokenType":"bearer","expiresIn":7200,"refreshToken":"RT-..."}}

-k hace falta porque el certificado del router es el de administración local, no uno público válido. El token dura 7200 s (2 h); refreshToken sirve para renovarlo sin volver a mandar client_secret.

Llamadas subsecuentes van con el access token en el header Authorization: AccessToken=<token> (no Bearer):

curl -sk "https://10.10.20.1/openapi/v1/<OMADAC_ID>/sites?page=1&pageSize=10" \
  -H "Authorization: AccessToken=<accessToken>"
# {"errorCode":0,"msg":"Success.","result":{"totalRows":1,...,"data":[{"siteId":"64f18718b68f3576cffd209d","name":"Controlador Comisariato",...}]}}

Cómo llegar a 10.10.20.1

Mismo vSwitch de Hyper-V que sr250 (10.10.20.0/24, ver hosts.md § on-premise Conkafecito) — pero 10.10.20.1 es el router/gateway físico en sí, no una de las VMs de sr250. Se llega vía NetBird sin necesidad de VPN/SSH extra: vm-dev es el routing peer de esa subred completa (netbird routes list la muestra como red disponible/seleccionada), así que cualquier host ya migrado a la cuenta nueva de NetBird (vm-playground incluido) la alcanza directo.

Véase también

• NetBird — vm-dev como routing peer de 10.10.20.0/24, la ruta real hacia el router
• Gestión de secretos — credenciales de la Open API
• Hyper-V (sr250) — mismo vSwitch, mismas VMs que comparten subred con el router
• conkafecito-observability — primer consumidor real de esta conexión: dashboards HTML + TUI en vm-playground