Claves de API
Cómo crear, administrar y usar claves de API para el acceso programático a la API REST de VergeOS, incluida la autenticación, los controles de acceso por IP, la configuración de caducidad y las mejores prácticas de seguridad.
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.
Creación de una clave API
Navegue a la gestión de claves API
Desde el menú principal de VergeOS, navegue a Sistema > Usuarios
Seleccione la cuenta de usuario que será propietaria de la clave API
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
Haga clic en + Nueva clave API en la parte inferior de la tabla de Claves API
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.
Haga clic en el + (más) icono para agregar una entrada
Ingrese una dirección IP (por ejemplo,
192.168.1.100) o rango CIDR (por ejemplo,192.168.1.0/24)Marque la casilla para habilitar la entrada
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.
Haga clic en el + (más) icono para agregar una entrada
Ingrese la dirección IP o rango CIDR que desea bloquear
Marque la casilla para habilitar la entrada
Guardar y recuperar la clave API
Revise que todos los ajustes sean correctos
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)
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.
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
En la tabla de Claves API, localice la clave que desea modificar
Haga clic en el Editar (lápiz) icono junto al nombre de la clave
Actualice los ajustes (nombre, descripción, expiración, listas de IP)
Haga clic en Enviar para guardar los cambios
Eliminar una clave API
En la tabla de Claves API, localice la clave que desea eliminar
Haga clic en el Eliminar (papelera) icono junto al nombre de la clave
Confirme la eliminación
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.
Uso de claves API
Formato de autenticación
Las claves API se usan en el encabezado HTTP Authorization como tokens Bearer:
Ejemplo de solicitud API
Almacenamiento de variables de entorno
Por seguridad, cargue las claves API desde variables de entorno en lugar de codificarlas directamente:
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 - Referencia completa de la API y endpoints
Última actualización
¿Te fue útil?