Claves API
Crea, limita, rota y revoca claves API en Kilo IoT — credenciales por integración para acceso REST y gRPC.
Las claves de API brindan acceso programático a sistemas externos al Servidor IoT de Kilo. Úselas para integrar canalizaciones CI/CD, sincronizar datos con plataformas de gestión de almacenes, alimentar scripts personalizados de análisis o informes, conectar sistemas SCADA o automatizar la configuración mediante sus propias herramientas. Cada clave se limita exactamente a los permisos que necesita, nada más. Si alguna vez se compromete una clave, puede revocarla o rotarla sin afectar ninguna otra integración.
¿Busca cómo usar la API? Los protocolos (REST y gRPC), la autenticación y los ejemplos se tratan en la API sección. Esta página trata sobre crear y administrar las claves con las que se autentican esas integraciones.
Navegación
Ir a Configuración → Claves de API en la barra lateral.
Crear una clave
Haz clic en Crear clave de API en la esquina superior derecha.
Introduce un Nombre para la clave. Es obligatorio. Elija un nombre que describa la integración; por ejemplo, "WMS-Sync-Production" o "Analytics-Pipeline-Staging". Identificará y administrará esta clave por su nombre.
Opcionalmente establezca una Caduca fecha usando el selector de fecha. La fecha seleccionable más temprana es hoy. Si se deja vacía, la clave permanecerá activa indefinidamente. Establezca una fecha de caducidad para acceso de contratistas o integraciones temporales.
Selecciona Ámbitos — se requiere al menos un ámbito. Marque solo los permisos que la integración realmente necesita. Consulte la Referencia de ámbitos a continuación.
Haga clic en el botón de confirmación para crear la clave.
Visualización única
Después de crearla, el valor completo de la clave se muestra una vez con un botón para copiar. Aparece una advertencia que dice:
"Copie esta clave ahora. No podrá verla de nuevo."
Almacene la clave inmediatamente en un administrador de secretos o bóveda. Una vez que cierre este diálogo, el valor completo de la clave desaparece; solo el prefijo de la clave permanece visible en la tabla. Si se pierde la clave, la única forma de recuperarla es rotarla.
Referencia de ámbitos
Los ámbitos controlan a qué puede acceder la clave. Cada ámbito tiene una Leer variante (recuperar datos) y una Escribir variante (crear, actualizar o eliminar). Conceda solo el conjunto mínimo que requiera su integración.
Los ámbitos disponibles pueden depender de su organización y plan. El historial de sensores de sensores y última vez visto usa un ámbito de telemetría independiente en lugar de Dispositivos: Leer — consulte la referencia de la API para el ámbito exacto que requiere cada endpoint.
Comandos
Ver definiciones de comandos del dispositivo e historial de ejecución
Crear y editar comandos, y enviarlos a dispositivos
Conexiones
Ver estado y configuración de conexión
Crear y modificar conexiones
Paneles
Ver paneles y datos de widgets
Crear, editar y eliminar paneles y widgets
Dispositivos
Ver lista de dispositivos y estado del Gemelo Digital
Registrar dispositivos, actualizar la configuración del dispositivo
Eventos
Ver historial de eventos del dispositivo
—
Registros
Ver registros del sistema y del dispositivo
Exportar registros
Organizaciones
Ver detalles de la organización y membresía
Modificar la configuración de la organización y la membresía
Reglas
Ver definiciones de reglas y estado de despliegue
Crear, editar, desplegar y eliminar reglas
Sensores
Ver definiciones y plantillas de métricas de sensores
Crear y modificar plantillas de sensores
Usuarios
Ver lista de usuarios y datos de perfil
Invitar, actualizar y eliminar usuarios
Principio de menor privilegio: otorgue solo los ámbitos que una integración usa — un script que lee la configuración del dispositivo solo necesita Dispositivos: Leer, no Dispositivos: Escribir ni ningún ámbito de organización. Limitar estrictamente los ámbitos reduce el impacto si alguna vez se expone una clave.
Tabla de claves de API
La página de Claves de API enumera todas las claves de su organización. Las columnas de la tabla son:
Nombre
La etiqueta asignada al crearla.
Prefijo de clave
Un prefijo corto del valor de la clave — suficiente para confirmar que está viendo la clave correcta sin exponer el secreto completo.
Ámbitos
Chips de permisos que muestran los ámbitos concedidos a esta clave.
Estado
Activa (verde), Rotada (amarillo) o Revocada (rojo).
Creada
Marca temporal cuando se creó la clave por primera vez.
Caduca
La fecha de caducidad, o "Nunca" si no se estableció ninguna.
Último uso
La marca temporal de la llamada API autenticada más reciente usando esta clave.
Las claves se ordenan de la más reciente a la más antigua de forma predeterminada. Los iconos de rotación y revocación aparecen solo en las claves activas: un icono de rotación para rotar y un icono de papelera para revocar.
Rotación de una clave
La rotación genera un nuevo valor de clave y desactiva inmediatamente la anterior. El estado de la clave antigua cambia a Rotada y ya no puede autenticar ninguna solicitud.
Use la rotación de forma periódica, o siempre que una clave pueda haber quedado expuesta; por ejemplo, si se registró accidentalmente, se confirmó en un repositorio o se compartió a través de un canal inseguro.
Haga clic en el icono de rotación en la fila de la clave que desea rotar.
Aparece un cuadro de diálogo de confirmación:
"Rotar clave de API — Esto generará una nueva clave y marcará la clave actual '[name]' como rotada. La clave antigua dejará de funcionar."
Confirme la rotación.
El valor de la nueva clave se muestra una vez. Cópielo inmediatamente. Actualice todos los sistemas que usan la clave antigua antes de que intenten hacer su próxima llamada a la API.
La clave rotada permanece visible en la tabla con Rotada estado a efectos de pista de auditoría.
Revocación de una clave
La revocación desactiva permanentemente una clave. La acción no se puede deshacer.
Haga clic en el icono de papelera de la fila de la clave.
Aparece un cuadro de diálogo de confirmación:
"Revocar clave de API — Esto revocará permanentemente la clave de API '[name]'. Esta acción no se puede deshacer."
Confirme la revocación.
El estado de la clave cambia a Revocada (rojo) y permanece visible en la tabla. Las claves revocadas no pueden autenticar ninguna solicitud. Aparecen en la pista de auditoría, por lo que tiene un historial completo de qué claves existían y cuándo se desactivaron.
Resultados esperados
Después de crear una clave:
La clave aparece inmediatamente en la tabla con estado Activa .
El Último uso la columna muestra un guion hasta que la clave hace su primera llamada API autenticada, luego se actualiza con cada uso posterior.
Las claves muestran una fecha de caducidad establecida al crearlas; verifique el estado actual de la clave en la columna Estado .
Solución de problemas
Sin permiso para crear claves de API: La administración de claves de API requiere derechos de acceso suficientes en su organización. Póngase en contacto con el administrador de su organización si el Crear clave de API botón no está disponible.
La clave se perdió antes de copiarla: El valor completo de la clave no se puede recuperar. Haga clic en Rotar en la fila de la clave para generar un nuevo valor. Actualice todas las integraciones con la nueva clave.
La integración devuelve errores de autenticación:
Confirme que el estado de la clave sea Activa (no Rotada ni Revocada).
Compruebe que la clave no haya superado su fecha de caducidad.
Verifique que la integración esté usando el valor correcto de la clave — compare el prefijo mostrado en la tabla con el prefijo de la clave en uso.
Confirme que la clave tenga el ámbito requerido para la operación que está intentando. Una clave solo de Dispositivos: Leerfallará en operaciones de escritura.
La clave revocada o rotada sigue aceptando solicitudes: Los cambios surten efecto inmediatamente. Si parece que una integración sigue autenticándose después de la revocación, confirme que no esté usando una clave diferente o una sesión en caché.
Buenas prácticas
Menor privilegio — Conceda solo los ámbitos que cada integración realmente usa. Audite regularmente.
Nombrado por propósito — Use nombres como "Warehouse-Sync-Prod", "Audit-Export-Script" o "CI-Pipeline-Staging" para que cualquier miembro del equipo pueda identificar al instante el propietario y el rol de la clave.
Establezca fechas de caducidad para acceso temporal — Las integraciones de contratistas, los scripts de prueba de concepto y los proyectos limitados en el tiempo siempre deben tener una caducidad. Elimine la necesidad de recordar revocar manualmente.
Rote según un calendario — Trate la rotación como mantenimiento rutinario y no como respuesta a incidentes. Un ciclo de rotación trimestral es una base razonable para claves de producción.
Almacenar en un administrador de secretos — Nunca incruste claves directamente en el código fuente, archivos de configuración o variables de entorno comprometidas al control de versiones. Use un administrador de secretos o una bóveda e inyéctelas en tiempo de ejecución.
Una clave por integración — Claves separadas significan que puede revocar el acceso de un sistema sin interrumpir ningún otro. Las claves compartidas multiplican el impacto de cualquier compromiso individual.
Última actualización