> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/run-the-platform/es/administracion-del-sistema/api-keys.md). # Claves de API ## Descripción general Las claves de API proporcionan autenticación para el acceso programático a la API REST de VergeOS y a los servicios integrados. Cada clave de API está asociada con una cuenta de usuario específica y hereda los permisos y niveles de acceso de ese usuario. Esto permite que las aplicaciones, los scripts y las herramientas de terceros interactúen con VergeOS sin requerir sesiones de inicio de sesión interactivas. **Usos comunes de las claves de API:** * Autenticación de la API REST para automatización e integración * Acceso al enrutador de IA compatible con OpenAI * Integración con herramientas de terceros (monitorización, orquestación, herramientas de IaC) * Autenticación de canalizaciones CI/CD ## Comprender la autenticación de claves de API Las claves de API en VergeOS funcionan como tokens Bearer en la cabecera HTTP Authorization. A diferencia de los tokens de sesión generados durante el inicio de sesión en la interfaz (que vencen tras la inactividad), las claves de API siguen siendo válidas hasta su fecha de vencimiento configurada o su eliminación manual. Cada clave de API hereda todos los permisos de su cuenta de usuario asociada. Una clave de API creada para un usuario de Administrador de inquilino tendrá privilegios de Administrador de inquilino, mientras que una clave para un Administrador del sistema tendrá acceso a todo el sistema. {% hint style="info" %} **Claves de API frente a tokens de sesión** Los tokens de sesión son credenciales temporales que vencen tras la inactividad. Las claves de API están diseñadas para un acceso programático de larga duración y siguen siendo válidas hasta su vencimiento o eliminación. {% endhint %} ## Crear una clave de API ### Ir a la administración de claves de API 1. Desde el menú principal de VergeOS, vaya a **Sistema > Usuarios** 2. Seleccione la cuenta de usuario que será propietaria de la clave de API 3. En el panel del usuario, haga clic en **Claves de API** widget para ver las claves existentes La sección Claves de API muestra una tabla con: * **Nombre**: Identificador descriptivo de cada clave * **Último inicio de sesión**: Marca de tiempo de autenticación más reciente * **IP del último inicio de sesión**: IP de origen de la última autenticación * **Caduca**: Días restantes hasta el vencimiento * **Creada**: Marca de tiempo de generación de la clave ### Crear nueva clave de API 1. Haga clic en **+ Nueva clave de API** en la parte inferior de la tabla Claves de API 2. El formulario se abre con dos paneles: **Clave de API** (izquierda) y **Acceso** (derecha) ### Configurar la clave de API **Nombre** (Obligatorio) Introduzca un identificador descriptivo para la clave de API. Un nombre claro ayuda con el seguimiento y la gestión de claves. **Descripción** (Opcional) Añada contexto adicional sobre el propósito de la clave, el solicitante o los sistemas relacionados. **Tipo de expiración** Elija cómo se gestiona el período de validez de la clave: * **Establecer fecha**: Defina una fecha de vencimiento específica (recomendado por seguridad) * **Nunca vence**: Cree una clave perpetua (úsela con precaución) **Caduca** (Cuando se seleccione "Establecer fecha") Use el selector de fecha y hora para establecer cuándo debe vencer la clave. Los períodos de vencimiento comunes son 30, 60 o 90 días. ### Configurar controles de acceso **Lista de IP permitidas** Restringa la clave de API a direcciones IP específicas o rangos CIDR. Solo las direcciones listadas pueden autenticarse con esta clave. 1. Haga clic en el **+ (más)** icono para añadir una entrada 2. Introduzca una dirección IP (p. ej., `192.168.1.100`) o un rango CIDR (p. ej., `192.168.1.0/24`) 3. Marque la casilla para habilitar la entrada 4. Añada entradas adicionales según sea necesario **Lista de IP denegadas** Bloquee direcciones IP o rangos específicos para que no usen esta clave, mientras permite todas las demás. 1. Haga clic en el **+ (más)** icono para añadir una entrada 2. Introduzca la dirección IP o el rango CIDR que desea bloquear 3. Marque la casilla para habilitar la entrada {% hint style="info" %} **Prioridad entre listas permitidas y denegadas** Cuando ambas listas están configuradas, la Lista de IP permitidas tiene prioridad. Si una dirección aparece en ambas listas, la lista permitida determina el acceso. {% endhint %} ### Guardar y recuperar la clave de API 1. Revise que todos los ajustes sean correctos 2. Haga clic en **Enviar** para generar la clave de API Una ventana emergente muestra la clave de API generada con dos opciones: * **Copiar**: Haga clic para copiar la cadena completa de la clave al portapapeles * **Guardar**: Haga clic para descargar la clave como un `.PAK` archivo de Clave de API Protegida {% hint style="danger" %} **Visualización única** La clave de API completa solo se muestra en el momento de la creación. Una vez que cierre esta ventana emergente, no se podrá recuperar la clave completa. Si pierde la clave, debe eliminarla y crear una nueva. {% endhint %} Después de guardar la clave de forma segura, cierre la ventana emergente. La nueva clave de API aparece en la tabla Claves de API. ## Administrar claves de API existentes ### Editar una clave de API 1. En la tabla Claves de API, localice la clave que desea modificar 2. Haga clic en el **Editar** icono de (lápiz) junto al nombre de la clave 3. Actualice la configuración (nombre, descripción, vencimiento, listas de IP) 4. Haga clic en **Enviar** para guardar los cambios {% hint style="info" %} **La cadena de la clave no se puede cambiar** Editar una clave de API solo actualiza sus metadatos y controles de acceso. La cadena real de la clave no se puede modificar. Para cambiar la cadena de la clave, debe crear una nueva clave de API y eliminar la antigua. {% endhint %} ### Eliminar una clave de API 1. En la tabla Claves de API, localice la clave que desea eliminar 2. Haga clic en el **Eliminar** icono de (papelera) junto al nombre de la clave 3. Confirme la eliminación {% hint style="warning" %} **Revocación inmediata** Eliminar una clave de API revoca inmediatamente todo el acceso. Cualquier aplicación o script que utilice la clave eliminada fallará en la autenticación. {% endhint %} ## Usar claves de API ### Formato de autenticación Las claves de API se usan en el encabezado HTTP Authorization como tokens Bearer: ``` Authorization: Bearer ``` ### Ejemplo de solicitud de API ```bash curl -X GET "https://your-vergeos-instance/api/v4/system" \\ -H "Authorization: Bearer your-api-key-string-here" \\ -H "Content-Type: application/json" ``` ### Almacenamiento en variables de entorno Por seguridad, cargue las claves de API desde variables de entorno en lugar de codificarlas de forma fija: ```bash # Establecer variable de entorno export VERGEOS_API_KEY="your-api-key-string" # Usar en la solicitud de API curl -X GET "https://your-vergeos-instance/api/v4/system" \\ -H "Authorization: Bearer ${VERGEOS_API_KEY}" ``` ## Consideraciones de seguridad **Trate las claves de API como contraseñas** Las claves de API proporcionan autenticación completa como el usuario asociado. Protéjalas con el mismo cuidado que las contraseñas. **Use restricciones de IP** Configure listas de IP permitidas siempre que sea posible para limitar dónde se puede usar la clave. Esto reduce significativamente el riesgo si una clave se ve comprometida. **Establezca fechas de vencimiento** Evite las claves perpetuas cuando sea posible. Un vencimiento regular obliga a rotar las claves y limita los períodos de exposición. **Supervise el uso de las claves** Revise regularmente los campos "Último inicio de sesión" y "IP del último inicio de sesión" para identificar patrones de acceso inesperados. **Elimine las claves no utilizadas** Elimine las claves de API que ya no sean necesarias para minimizar su superficie de ataque. ## Solución de problemas **La autenticación con la clave de API falla** Verifique que la clave esté incluida correctamente en el encabezado Authorization como un token Bearer. Compruebe si hay espacios extra o truncamiento. **Acceso denegado con una clave válida** Revise las listas de IP permitidas/denegadas. Es posible que su IP de origen no esté permitida o que esté en la lista denegada. **La clave ha vencido** Revise la columna "Vence" en la tabla Claves de API. Cree una nueva clave si la anterior ha vencido. **No se puede recuperar la clave perdida** Las claves de API no se pueden recuperar después de cerrar la ventana emergente inicial de creación. Elimine la clave perdida y cree una nueva. ## Recursos relacionados * [Documentación de la API REST de VergeOS](/knowledge-base/es/automation-api/verge-api-guide.md) - Referencia completa de la API y puntos finales --- # 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.verge.io/run-the-platform/es/administracion-del-sistema/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.