La API de Fing Cloud permite que tus propios scripts, paneles y automatizaciones lean lo que Fing sabe sobre tus redes: espacios de trabajo, redes, dispositivos, contactos, eventos, resultados de pruebas de velocidad y análisis de vulnerabilidades del router. Te autenticas con un ID de cliente y un secreto que creas en tu cuenta, los intercambias por un token de corta duración y llamas a la API mediante HTTPS. En este artículo se explica cómo crear y gestionar esas credenciales, cómo realizar tu primera llamada y cómo mantener las credenciales seguras.
Beta, para cuentas de Fing Professional
La API de Cloud es una versión preliminar para cuentas de Fing Professional. Por ahora es de solo lectura, y los endpoints, ámbitos y límites pueden cambiar mientras dure la beta.
¿Quieres conectar una aplicación o un asistente de IA?
IFTTT y los agentes de IA se conectan mediante un inicio de sesión, sin necesidad de usar tus propias credenciales. Consulta Conectar aplicaciones de terceros y agentes de IA a tu cuenta de Fing.
Para qué sirve la API de Cloud
Úsala cuando quieras tener datos de Fing en un lugar al que Fing no accede por sí mismo:
- un panel doméstico o de oficina que muestre qué dispositivos están conectados y cuándo se realizó la última prueba de velocidad;
- un script que exporte el inventario de dispositivos de todas las redes que gestionas;
- una herramienta de alertas que lea el registro de eventos y te avise sobre nuevos dispositivos o interrupciones del servicio;
- cualquier plataforma de integración que pueda llamar a una API REST con un token de portador.
La lista completa de endpoints, parámetros y esquemas de respuesta se encuentra en la referencia de la API de Cloud. La especificación de OpenAPI disponible en https://app.fing.com/cloud/docs/api-spec permite generar un cliente en el lenguaje que prefieras.
Dónde gestionar tus credenciales
Inicia sesión en app.fing.com, abre Acceso desde la navegación de la cuenta y selecciona la pestaña API de Cloud. Mis credenciales muestra los clientes que has creado:
- Nombre: la etiqueta que has asignado al cliente, con una insignia Inactivo cuando lo has pausado.
- Secreto: los cuatro últimos caracteres del secreto, para que puedas identificar qué secreto utiliza un script. El secreto completo no vuelve a mostrarse después de su creación.
- Ámbitos: lo que puede hacer un token emitido para este cliente.
- Creado y Último uso: cuándo creaste el cliente y cuándo se utilizó su secreto por última vez para solicitar un token.
Las cuentas sin un plan Professional pueden ver esta lista, pero no pueden crear ni modificar clientes.
Crear un cliente
- En la pestaña API de Cloud, haz clic en Crear cliente.
- Introduce un nombre que indique para qué sirve el cliente, como «Panel doméstico», y haz clic en Crear.
- Fing muestra el ID de cliente y el secreto de cliente. Cópialos mediante los botones Copiar y guárdalos en un lugar seguro, como un gestor de contraseñas o el almacén de secretos de tu herramienta.
- Haz clic en He guardado el secreto. El cuadro de diálogo no se puede cerrar de otra forma, porque el secreto no volverá a mostrarse.
Un cliente nuevo comienza con los ámbitos api_read, api_write y api_provisioning, y está activo. Durante la beta, solo api_read tiene endpoints asociados; los otros dos están reservados para las operaciones de escritura y aprovisionamiento que se incorporarán más adelante.
Trata el secreto como una contraseña
Cualquiera que tenga el ID de cliente y el secreto puede leer tus redes. No los pegues nunca en un chat, una incidencia ni un repositorio público, y asigna a cada script su propio cliente para poder revocar uno sin interrumpir los demás.
Realiza tu primera llamada
1. Solicita un token de acceso
La API de Cloud utiliza la concesión de credenciales de cliente de OAuth 2.0. Intercambia el ID de cliente y el secreto por un token:
curl -X POST https://app.fing.com/rest/auth/external/token \
-d grant_type=client_credentials \
-d client_id=YOUR_CLIENT_ID \
-d client_secret=YOUR_CLIENT_SECRETLa respuesta contiene el token, su duración en segundos y los ámbitos que incluye:
{
"token_type": "Bearer",
"access_token": "…",
"expires_in": 3600,
"scope": "api_read api_write api_provisioning"
}Un token es válido durante una hora y no incluye un token de actualización: cuando caduque, solicita uno nuevo con la misma llamada. Solicita un token cuando se inicie el script, en lugar de hacerlo una vez por cada llamada a la API.
2. Llama a la API
Envía el token en la cabecera Authorization de cada solicitud:
curl https://app.fing.com/cloud/v1/networks \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Esto muestra tus redes. Cada una incluye un networkRef que los demás endpoints utilizan como entrada, por ejemplo /cloud/v1/network/{networkRef}/devices para consultar sus dispositivos. Consulta la referencia de la API de Cloud para ver todos los endpoints.
Errores y límites
| Estado | Qué significa | Qué hacer |
|---|---|---|
401 |
Falta el token, ha caducado o no es válido, o el cliente se ha pausado o eliminado. | Solicita un token nuevo. Si tampoco funciona, comprueba el cliente en Mis credenciales. |
403 |
El token no incluye el ámbito que requiere el endpoint. | Comprueba los ámbitos del cliente y solicita un token nuevo después de modificarlos. |
429 |
El cliente ha superado su límite de solicitudes. | Espera el tiempo indicado en las cabeceras que aparecen a continuación y vuelve a intentarlo. |
Cada respuesta informa de los límites aplicables a tu cliente. RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset describen el límite a corto plazo; X-RateLimit-Limit-Monthly, X-RateLimit-Remaining-Monthly y X-RateLimit-Reset-Monthly describen la cuota mensual. Si un límite no se aplica a tu cliente, no se incluye.
Gestiona tus clientes
Cada fila de Mis credenciales tiene tres botones: editar, rotar y eliminar.
Cambia el nombre, modifica los ámbitos o pausa un cliente
- Haz clic en el botón del lápiz de la fila del cliente.
- Cambia el Nombre, marca o desmarca Ámbitos, o desactiva Activo para pausar el cliente.
- Haz clic en Guardar.
Debe quedar marcado al menos un ámbito. Los cambios en los ámbitos se aplican a los tokens emitidos a partir de ese momento; un token emitido anteriormente conserva sus ámbitos hasta que caduque. Un cliente pausado no puede obtener tokens nuevos, pero conserva su ID, secreto y configuración, por lo que es la opción adecuada si quieres detener temporalmente un script sin volver a emitir las credenciales.
Rota un secreto
Rota un secreto cuando pueda haberse filtrado, cuando se marche una persona que lo conocía o siguiendo tu propio calendario.
- Haz clic en el botón de rotación, representado por unas flechas circulares, en la fila del cliente.
- Lee el mensaje de confirmación y haz clic en Rotar secreto.
- Copia el nuevo secreto del cuadro de diálogo y actualiza todos los scripts que utilizan este cliente; después, haz clic en He guardado el secreto.
El secreto antiguo deja de funcionar inmediatamente para las nuevas solicitudes de tokens. Los tokens de acceso emitidos antes de la rotación siguen funcionando hasta que caduquen, por lo que un script en ejecución dispone de hasta una hora para empezar a utilizar el nuevo secreto. El ID de cliente no cambia.
Eliminar un cliente
- Haz clic en el botón de la papelera de la fila del cliente.
- Lee el mensaje de confirmación y haz clic en Eliminar cliente.
El cliente se elimina permanentemente y todos los tokens emitidos para él se revocan de inmediato, por lo que todo lo que siga utilizando estas credenciales dejará de funcionar inmediatamente. Si solo quieres pausarlo, desactiva el cliente.
Qué ocurre cuando cambia tu plan
Para crear y gestionar clientes necesitas un plan Fing Professional. Si tu cuenta cambia a otro plan, tus clientes seguirán apareciendo en Mis credenciales, pero los botones de crear, editar, rotar y eliminar estarán desactivados hasta que vuelvas a tener Professional; entonces podrás eliminar los clientes que ya no quieras.
Lista de comprobación de seguridad
- Guarda los secretos en un gestor de contraseñas, una variable de entorno o el almacén de secretos de tu plataforma, nunca en el código fuente.
- Crea un cliente por cada script o herramienta y asígnale un nombre según su función, para que una filtración afecte a un solo elemento y Último uso te indique qué clientes siguen activos.
- Elimina los clientes que ya no utilices y pausa los que vayas a necesitar de nuevo.
- Rota un secreto en cuanto sospeches que se ha filtrado. Si no puedes actualizar el script a tiempo, pausa o elimina el cliente.
Solución de problemas
Comprueba que la solicitud sea un POST con grant_type, client_id y client_secret como campos de formulario, no como JSON, y que el secreto sea el actual. Después de una rotación, se rechaza el secreto anterior.
Es posible que el cliente se haya pausado o eliminado. Abre la pestaña API de Cloud: un cliente pausado muestra la insignia Inactivo; si se ha eliminado, ya no aparece en la lista.
Tu cuenta no tiene un plan Fing Professional o el navegador sigue mostrando la página anterior a un cambio de plan. Comprueba tu plan en Cuenta y, después, en Suscripción, y vuelve a cargar la página.
No se puede recuperar. Rota el secreto para obtener uno nuevo y actualiza tus scripts.
¿Necesitas ayuda?
Haz clic en el botón Enviar una solicitud situado en la parte superior derecha de la página e incluye el código de estado y el endpoint al que has llamado. No incluyas nunca el secreto de cliente ni un token.
Comentarios
0 comentariosInicie sesión para dejar un comentario.