> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-es/kilo-iot-server/settings/api-keys.md).
# 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](/kilo-docs-es/kilo-iot-server/api.md) 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
1. Haz clic en **Crear clave de API** en la esquina superior derecha.
2. 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.
3. 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.
4. Selecciona **Ámbitos** — se requiere al menos un ámbito. Marque solo los permisos que la integración realmente necesita. Consulte la [Referencia de ámbitos](#scope-reference) a continuación.
5. 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](/kilo-docs-es/kilo-iot-server/api.md) para el ámbito exacto que requiere cada endpoint.
| Ámbito | Leer concede acceso a | Escribir concede acceso a |
| ------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **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:
| Columna | Descripción |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **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.
1. Haga clic en el icono de rotación en la fila de la clave que desea rotar.
2. 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."**
3. Confirme la rotación.
4. 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.
1. Haga clic en el icono de papelera de la fila de la clave.
2. 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."**
3. 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: Leer*fallará 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-es/kilo-iot-server/settings/api-keys.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
