> 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/automate-protect-and-extend/es/superficies-de-administracion-compartidas/api-keys.md). # Claves de API ## Descripción general Las claves API proporcionan autenticación para el acceso programático a la API REST de VergeOS y a los servicios integrados. Cada clave API está asociada a una cuenta de usuario específica y hereda los permisos y niveles de acceso de ese usuario. Esto permite que aplicaciones, scripts y herramientas de terceros interactúen con VergeOS sin requerir sesiones de inicio de sesión interactivas. **Usos comunes de las claves API:** * Autenticación de la API REST para automatización e integración * Acceso al enrutador de IA compatible con OpenAI * Integración de herramientas de terceros (monitorización, orquestación, herramientas IaC) * Autenticación de canalizaciones CI/CD ## Comprender la autenticación con clave API Las claves API en VergeOS funcionan como tokens Bearer en el encabezado HTTP Authorization. A diferencia de los tokens de sesión generados durante el inicio de sesión en la interfaz (que expiran tras inactividad), las claves API siguen siendo válidas hasta su fecha de expiración configurada o su eliminación manual. Cada clave API hereda todos los permisos de la cuenta de usuario asociada. Una clave API creada para un usuario de Administrador de Tenant tendrá privilegios de Administrador de Tenant, mientras que una clave para un Administrador del Sistema tendrá acceso de todo el sistema. {% hint style="info" %} **Claves API frente a tokens de sesión** Los tokens de sesión son credenciales temporales que expiran tras inactividad. Las claves API están diseñadas para acceso programático de larga duración y permanecen válidas hasta su expiración o eliminación. {% endhint %} ## Creación de una clave API ### Navegue a la gestión de claves API 1. Desde el menú principal de VergeOS, navegue a **Sistema > Usuarios** 2. Seleccione la cuenta de usuario que será propietaria de la clave API 3. En el panel de control del usuario, haga clic en el **Claves de API** widget para ver las claves existentes La sección Claves 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 * **Vence**: Días restantes hasta la expiración * **Creado**: Marca de tiempo de generación de la clave ### Crear nueva clave API 1. Haga clic en **+ Nueva clave API** en la parte inferior de la tabla de Claves API 2. El formulario se abre con dos paneles: **Clave API** (izquierda) y **Acceso** (derecha) ### Configurar ajustes de la clave API **Nombre** (Obligatorio) Ingrese un identificador descriptivo para la clave API. Un nombre claro ayuda con el seguimiento y la gestión de claves. **Descripción** (Opcional) Agregue contexto adicional sobre el propósito de la clave, el solicitante o los sistemas relacionados. **Tipo de vencimiento** Elija cómo se gestiona el período de validez de la clave: * **Establecer fecha**: Defina una fecha de expiración específica (recomendado por seguridad) * **Nunca expirar**: Cree una clave perpetua (úsela con precaución) **Vence** (Cuando se selecciona "Establecer fecha") Use el selector de fecha/hora para establecer cuándo debe expirar la clave. Los períodos de expiración comunes son 30, 60 o 90 días. ### Configurar controles de acceso **Lista de IP permitidas** Restrinja la clave 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 agregar una entrada 2. Ingrese una dirección IP (por ejemplo, `192.168.1.100`) o rango CIDR (por ejemplo, `192.168.1.0/24`) 3. Marque la casilla para habilitar la entrada 4. Agregue entradas adicionales según sea necesario **Lista de IP denegadas** Bloquee direcciones IP específicas o rangos para que no usen esta clave, permitiendo todas las demás. 1. Haga clic en el **+ (más)** icono para agregar una entrada 2. Ingrese la dirección IP o rango CIDR que desea bloquear 3. Marque la casilla para habilitar la entrada {% hint style="info" %} **Prioridad de la lista de permitidos frente a la lista de denegados** Cuando ambas listas están configuradas, la Lista de IP permitidas tiene prioridad. Si una dirección aparece en ambas listas, la Lista de permitidos determina el acceso. {% endhint %} ### Guardar y recuperar la clave API 1. Revise que todos los ajustes sean correctos 2. Haga clic en **Enviar** para generar la clave API Aparece una ventana emergente que muestra la clave 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 archivo `.PAK` (archivo de Clave API protegida) {% hint style="danger" %} **Visualización única** La clave 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 asegurar la clave, cierre la ventana emergente. La nueva clave API aparece en la tabla de Claves API. ## Administrar claves API existentes ### Editar una clave API 1. En la tabla de Claves API, localice la clave que desea modificar 2. Haga clic en el **Editar** (lápiz) icono junto al nombre de la clave 3. Actualice los ajustes (nombre, descripción, expiración, 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 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 API y eliminar la anterior. {% endhint %} ### Eliminar una clave API 1. En la tabla de Claves API, localice la clave que desea eliminar 2. Haga clic en el **Eliminar** (papelera) icono junto al nombre de la clave 3. Confirme la eliminación {% hint style="warning" %} **Revocación inmediata** Eliminar una clave API revoca inmediatamente todo el acceso. Cualquier aplicación o script que use la clave eliminada fallará en la autenticación. {% endhint %} ## Uso de claves API ### Formato de autenticación Las claves API se usan en el encabezado HTTP Authorization como tokens Bearer: ``` Authorization: Bearer ``` ### Ejemplo de solicitud API ```bash curl -X GET "https://tu-instancia-vergeos/api/v4/system" \\ -H "Authorization: Bearer tu-cadena-de-clave-api" \\ -H "Content-Type: application/json" ``` ### Almacenamiento de variables de entorno Por seguridad, cargue las claves API desde variables de entorno en lugar de codificarlas directamente: ```bash # Establecer variable de entorno export VERGEOS_API_KEY="tu-cadena-de-clave-api" # Usar en la solicitud API curl -X GET "https://tu-instancia-vergeos/api/v4/system" \\ -H "Authorization: Bearer ${VERGEOS_API_KEY}" ``` ## Consideraciones de seguridad **Trate las claves API como contraseñas** Las claves 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 puede usarse la clave. Esto reduce significativamente el riesgo si una clave se ve comprometida. **Establecer fechas de expiración** Evite las claves perpetuas cuando sea posible. La expiración regular obliga a rotar las claves y limita las ventanas de exposición. **Supervisar 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. **Eliminar claves no utilizadas** Elimine las claves API que ya no sean necesarias para minimizar su superficie de ataque. ## Solución de problemas **La autenticación con clave API falla** Verifique que la clave esté incluida correctamente en el encabezado Authorization como un token Bearer. Compruebe si hay espacios adicionales 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 de denegadas. **Clave expirada** Revise la columna "Expira" en la tabla de Claves API. Cree una nueva clave si la anterior ha expirado. **No se puede recuperar una clave perdida** Las claves API no se pueden recuperar después de cerrar la ventana emergente de creación inicial. 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 endpoints --- # 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/automate-protect-and-extend/es/superficies-de-administracion-compartidas/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.