Usa la API de Fing Cloud con tus propios scripts y herramientas

¿Tiene más preguntas? Enviar una solicitud

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.

The Cloud API tab: a beta notice, the My credentials table with two clients, Home dashboard and a paused Backup script, their masked secrets, scope badges, created and last used dates, the edit, rotate and delete buttons, and links to the API documentation and this guide.

Las cuentas sin un plan Professional pueden ver esta lista, pero no pueden crear ni modificar clientes.

Crear un cliente

  1. En la pestaña API de Cloud, haz clic en Crear cliente.
  2. Introduce un nombre que indique para qué sirve el cliente, como «Panel doméstico», y haz clic en Crear.
  3. 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.
  4. 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.

The Client created dialog: the client id and the client secret in two read-only fields with Copy buttons, a warning that the secret is shown only once, and the I have saved the secret button.

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_SECRET

La 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

  1. Haz clic en el botón del lápiz de la fila del cliente.
  2. Cambia el Nombre, marca o desmarca Ámbitos, o desactiva Activo para pausar el cliente.
  3. Haz clic en Guardar.

The Edit client dialog: the name field, the three API scopes as tick boxes with descriptions, the Active switch, and the Cancel and Save buttons.

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.

  1. Haz clic en el botón de rotación, representado por unas flechas circulares, en la fila del cliente.
  2. Lee el mensaje de confirmación y haz clic en Rotar secreto.
  3. 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.

The Rotate the secret? confirmation for the Home dashboard client, explaining that the current secret stops working for new token requests while issued tokens keep working until they expire, with Cancel and Rotate secret buttons.

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

  1. Haz clic en el botón de la papelera de la fila del cliente.
  2. 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

El endpoint de tokens responde «invalid_request» o «invalid_grant»

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.

Todas las llamadas responden 401 aunque el token sea reciente

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.

El botón Crear cliente está desactivado

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.

He perdido el secreto

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.

Artículos en esta sección

¿Fue útil este artículo?
Usuarios a los que les pareció útil: 0 de 0
Compartir

Comentarios

0 comentarios

Inicie sesión para dejar un comentario.