Tokens de API

Los tokens de API te permiten conectar sistemas externos, scripts y herramientas a la plataforma Mirox con credenciales con alcance limitado y revocables que nunca exponen tu contraseña. Cada token autentica peticiones máquina a máquina en tu nombre, de modo que puedes exportar métricas y automatizar tus integraciones sin compartir tu inicio de sesión.

Concepto de token

Cada token pertenece al usuario que lo creó y se comporta como ese usuario, dentro de unos límites:

  • Vinculado a tu cuenta: un token actúa en tu nombre, y todo lo que hace se te atribuye a ti en el registro de auditoría.
  • Tope de permisos: un token nunca puede alcanzar nada a lo que tú mismo no puedas acceder. Tu propio rol y tu acceso a recursos siempre limitan lo que el token ve.
  • Acotado por grupo de permisos: eliges un grupo de permisos en el momento de la creación para acotar aún más el token (ver abajo).
  • Se muestra una sola vez: el valor completo del token se muestra una única vez cuando lo creas. Guárdalo de forma segura; Mirox solo conserva una copia con hash y nunca podrá volver a mostrarlo.
  • Hecho para la automatización: a un token nunca se le pide un segundo factor y las reglas de inicio de sesión de tu organización no lo finalizan. Consulta Tokens y autenticación de dos factores.

Esto mantiene la automatización rastreable: incluso si un token se ve comprometido, está limitado a un único alcance, es fácil de revocar y queda aislado de tus otros tokens.

Grupos de permisos

Cuando creas un token eliges un grupo de permisos que define lo que puede hacer:

GrupoLo que el token puede hacer
Acceso completoActúa con tu acceso completo: cada superficie de API que puedas alcanzar.
Metric ExportLeer únicamente la exportación de datos: métricas como series temporales, plantillas de exportación, el catálogo de métricas, información de la planta y eventos. No puede cambiar nada.
Base de datos de series temporalesLeer únicamente las series de medición brutas.

Un grupo nunca amplía tu acceso; solo acota el token en relación con tus propios permisos. Para conocer la definición completa de cada grupo, consulta la sección grupos de permisos de API de la documentación del sistema de permisos.

Ajusta el grupo a la tarea

Concede a cada integración el grupo más restringido que siga funcionando. Un libro de Excel o un script que lee exportaciones solo necesita Metric Export; un cliente que lee las series de medición brutas solo necesita Base de datos de series temporales. Esto limita el radio de impacto si un token se filtra.

Crear y gestionar tokens

Gestionas tus tokens desde tu perfil. La plataforma cubre todo el ciclo de vida:

Crear un token

  • Nombre y descripción: una etiqueta y una nota claras para que recuerdes para qué sirve cada token.
  • Grupo de permisos: elige uno de los grupos anteriores.
  • Caducidad: opcional. Los tokens tienen por defecto una vigencia de un año, y puedes establecer cualquier caducidad hasta un máximo de cinco años.
  • Revelación única: el token completo se muestra una vez en la creación, y nunca más.

Puedes tener hasta 64 tokens activos por cuenta.

Crear y rotar, en el navegador

Los tokens se crean y se rotan en el navegador, con la sesión iniciada en Mirox. No puedes usar un token de API para crear o rotar otro: esto evita que un token filtrado cree más tokens de forma silenciosa.

Rotar un token

La rotación reemplaza el secreto de un token en su sitio sin cambiar su nombre, descripción ni grupo de permisos:

  • Se emite un nuevo secreto y se muestra una vez.
  • El secreto antiguo deja de funcionar de inmediato.
  • La caducidad se reinicia y el historial de uso se borra.

La rotación es la forma recomendada de renovar integraciones de larga duración de forma programada, o de responder a una sospecha de filtración, sin reconfigurar qué integración usa qué token.

Monitorizar y revocar

  • Inventario: lista todos tus tokens con su nombre, grupo de permisos, fechas de creación y caducidad.
  • Información de uso: consulta cuándo se usó por última vez cada token, junto con la IP, la ubicación, el navegador y el sistema operativo capturados en ese momento. El valor del token en sí nunca se vuelve a mostrar.
  • Revocación inmediata: elimina un token para invalidarlo al instante. Revocar un token nunca afecta a los demás.

Tokens y autenticación de dos factores

Un token de API está hecho para scripts e integraciones que funcionan sin una persona al teclado. Por eso no se le aplican las reglas de inicio de sesión pensadas para personas:

  • Sin segundo factor. A un token nunca se le pide un código, tenga o no tu cuenta autenticación de dos factores (2FA).
  • Las reglas de inicio de sesión no lo finalizan. Tu organización puede fijar cuánto dura un inicio de sesión en la aplicación web y en la aplicación móvil. Un token no es un inicio de sesión: sigue funcionando hasta su propia fecha de caducidad, o hasta que lo rotes o lo revoques. Que se cierre tu sesión no detiene tus tokens.
  • Una exigencia de 2FA no lo cambia. Cuando una organización exige 2FA para acceder a sus plantas, esa regla se aplica a las personas con sesión iniciada en la aplicación web y en la aplicación móvil. No cambia lo que un token existente puede alcanzar.

Una regla sí se aplica: mientras tu propia organización exija 2FA y tu cuenta no tenga segundo factor, no puedes crear un token nuevo. Activa primero la 2FA (aplicación de autenticación o passkey) — consulta Autenticación de dos factores. Mientras tanto, tus tokens existentes siguen funcionando.

Como un token no está protegido por un segundo factor, trátalo como una contraseña: guárdalo en un lugar seguro, dale el grupo de permisos más restringido, fija una caducidad y revócalo cuando ya no haga falta. Para las reglas de la organización, consulta Política de seguridad de la organización.

Casos de uso habituales

Los tokens de API admiten una amplia variedad de escenarios de integración.

Metric Export

Un token Metric Export lee todos los enlaces de Metric Export y de la exportación heredada:

  • Actualizar libros de Excel y cuadros de mando de BI a partir de un enlace de exportación.
  • Alimentar datos de producción y rendimiento en almacenes de datos y canalizaciones de análisis.
  • Crear tus propios informes a partir de los datos exportados.

El token no puede crear ni modificar plantillas, métricas ni ninguna otra cosa. Los informes que genera el propio Mirox no se controlan con tokens de API: se generan, publican y descargan en la aplicación.

Acceso a métricas de series temporales

  • Leer las series de medición brutas de tus plantas, las mismas series que lee Grafana.
  • Conectar herramientas de análisis de solo lectura que hablan el lenguaje de consulta del almacén de series temporales.

Seguridad y control

  • Aislamiento de tokens: un token comprometido nunca expone tu contraseña ni tus otros tokens.
  • Rotación programada: rota periódicamente los tokens de larga duración mediante la acción de rotar, manteniendo la misma configuración.
  • Validez limitada en el tiempo: establece una caducidad para que los tokens abandonados expiren automáticamente.
  • Atribución completa: cada acción que realiza un token queda registrada a tu nombre, de modo que el uso sigue siendo rastreable y auditable.

Funciones relacionadas