Tokens de API

Los tokens de API dan a tus sistemas externos y scripts un acceso seguro y delimitado a la plataforma Mirox sin compartir tus credenciales de acceso. Los creas en tu perfil, das a cada uno solo los permisos que necesita y puedes revocar o rotar cualquiera de ellos en cualquier momento.

Resumen

A diferencia de tu nombre de usuario y contraseña, un token de API:

• Lleva un grupo de permisos específico que limita lo que puede alcanzar
• Tiene una fecha de caducidad configurable (por defecto un año, máximo cinco años)
• Puede ser rotado a un nuevo secreto o revocado individualmente, sin afectar a tu cuenta ni a tus otros tokens
• Registra su propio historial de uso (hora del último uso, IP de origen, ubicación, navegador y sistema operativo) para que puedas ver cómo se comporta cada integración

Puedes tener hasta 64 tokens a la vez.

Crear tokens de API

Los tokens de API pueden crearse a través de la interfaz web de Mirox:

1. Inicia sesión en tu cuenta de Mirox
2. Abre el menú de perfil (arriba a la derecha) y elige Perfil
3. Selecciona la pestaña "Tokens de API"
4. Haz clic en "Crear nuevo token"
5. Configura los ajustes del token:
   • Nombre (etiqueta descriptiva para el token)
   • Fecha de caducidad (por defecto 1 año si no se especifica, máximo 5 años)
   • Alcance de permisos (recursos y acciones específicos a los que puede acceder el token)
6. Haz clic en "Generar token"

Abrir en Mirox: Perfil ▸ Tokens de API — gestiona tus tokens desde el menú de perfil ▸ Perfil y luego la pestaña "Tokens de API".

Buenas prácticas de seguridad de los tokens

Al trabajar con tokens de API:

1. Almacénalos de forma segura - Trata los tokens como contraseñas; nunca los incrustes directamente en las aplicaciones
2. Usa variables de entorno - Almacena los tokens en variables de entorno o en almacenes de credenciales seguros
3. Limita el alcance - Crea tokens con los permisos mínimos necesarios para la integración
4. Establece caducidades apropiadas - Usa periodos de caducidad más cortos para integraciones temporales
5. Planifica la rotación - Configura recordatorios en el calendario antes de la caducidad del token para garantizar la continuidad del servicio
6. Rota con regularidad - Usa la acción Rotar integrada para renovar periódicamente el secreto de un token antes de su caducidad, especialmente en sistemas de producción
7. Revoca los no usados - Revoca de inmediato los tokens que ya no se necesiten
8. Monitoriza el uso - Audita regularmente la actividad de los tokens a través de la interfaz de Mirox

Usar tokens de API

Los tokens de API se usan en las solicitudes HTTP como token Bearer en la cabecera Authorization:

Authorization: Bearer your-api-token

Los siguientes ejemplos requieren un token en el grupo de permisos Full Access.

Ejemplo de solicitud HTTP

GET /api/v1/park HTTP/1.1
Host: service.mirox.io
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Ejemplo con Curl

curl -X GET \
  https://service.mirox.io/api/v1/park \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json'

Permisos de los tokens

Los tokens de API están sujetos a la capa de permisos de tokens de API de la plataforma Mirox. Puntos clave sobre los permisos de los tokens:

• Los tokens heredan los permisos del usuario que los creó (nunca más)
• Los permisos pueden restringirse aún más por funcionalidad
• Los tokens operan dentro del mismo modelo de permisos jerárquico que las cuentas de usuario
• Todos los controles de seguridad de la plataforma se aplican al acceso basado en tokens

Para información detallada sobre cómo encajan los tokens de API dentro de la arquitectura general de permisos, consulta la documentación del Sistema de permisos.

Grupos de permisos

Cuando creas un token, eliges uno de tres grupos de permisos que delimitan lo que puede alcanzar:

• Full Access — concede al token los mismos permisos que tu cuenta de usuario, dentro de tu alcance. Cualquier servicio que lo use puede actuar en tu nombre en toda la plataforma, así que elige esta opción solo cuando una integración realmente necesite un acceso amplio.
• Reporting — restringe el token a las funciones de informes: generar informes y exportar datos.
• Timeseries Database — restringe el token a los endpoints de consulta de series temporales, para extraer datos de medición de forma programática (por ejemplo, con MiroxQL).

Elige el grupo más restrictivo que cubra tu integración. Un token de Reporting o Timeseries Database no puede alcanzar nada fuera de su alcance, lo que limita el radio de impacto si alguna vez se filtra.

Gestión del ciclo de vida de los tokens

Monitorizar el uso de los tokens

Sigue la actividad de los tokens de API a través de:

1. La sección "Tokens de API" en tu perfil
2. Los registros de auditoría que muestran cuándo y cómo se usó cada token

Rotar tokens

La rotación reemplaza el secreto de un token sin cambiar su nombre, su grupo de permisos ni su lugar en tu lista de tokens. Esto te permite renovar una clave según una planificación, o reaccionar ante una posible filtración, manteniendo la misma entrada de token en la configuración de tus integraciones.

Para rotar un token:

1. Ve a la sección "Tokens de API" en tu perfil
2. Localiza el token en la lista y elige "Rotar"
3. Copia el nuevo secreto de inmediato: solo se muestra una vez
4. Actualiza el secreto en la integración que lo utiliza

La rotación emite un nuevo secreto, reinicia la ventana de caducidad y borra el historial de uso registrado del token. El secreto antiguo deja de funcionar de inmediato, así que actualiza tus integraciones como parte de la rotación.

Revocar tokens

Para revocar un token:

1. Ve a la sección "Tokens de API" en tu perfil
2. Localiza el token en la lista
3. Haz clic en "Revocar"
4. Confirma la acción

La revocación surte efecto de inmediato, y cualquier solicitud posterior que use el token fallará.

Limitaciones de uso

Los tokens de API están sujetos a los mismos límites de tasa que las cuentas de usuario normales. Para más detalles sobre estas limitaciones, consulta la sección de Limitación de tasa en la documentación de Conceptos de autenticación.

Resolución de problemas

Problemas comunes de los tokens y sus soluciones:

Ejemplos de código

Para código funcional que usa un token de API de principio a fin, consulta:

• Generador de informes externos — un script de Python que se autentica con un token y extrae una exportación de métricas
• MiroxQL — el lenguaje de consulta para extraer datos de series temporales con un token de Timeseries Database

Funciones relacionadas

• Resumen de la API — el punto de entrada a la API REST de Mirox y su documentación en vivo
• Sistema de permisos — cómo encajan los grupos de permisos de los tokens en el modelo de roles de la plataforma
• Autenticación — sesiones, inicio de sesión de dos factores y los límites de tasa que también se aplican a los tokens
• MiroxQL — consulta datos de series temporales de forma programática con un token de Timeseries Database
• API de exportación de métricas — exporta datos de medición e informes con un token de Reporting