KapsuleHost le proporciona dos superficies para desarrolladores: claves API con alcance para leer su cuenta mediante programación, y una caché de compilación remota que acelera las compilaciones de Turborepo y Nx en sus propias máquinas y ejecutores de CI.
Ninguna está habilitada por defecto. Ambas se crean desde Configuración, y ambas le entregan un secreto exactamente una vez.
Crear una clave API
Las claves API se encuentran en Configuración, luego Seguridad, en la tarjeta Claves API.
- Vaya a Configuración, luego Seguridad.
- Desplácese hasta Claves API y haga clic en Nueva clave.
- Asigne un nombre a la clave. El campo sugiere "Nombre de clave (por ejemplo, Mi script de automatización)". El nombre es solo para usted, así que hágalo indicar dónde se utilizará la clave.
- Haga clic en los chips de alcance para seleccionar qué puede hacer la clave. Tres alcances de lectura están preseleccionados:
read:sites,read:emailyread:domains. Haga clic en un chip para añadirlo o eliminarlo. - Haga clic en Crear.
La clave completa aparece una vez, en un panel verde encabezado "Copiar ahora". Cópiela directamente en su almacén de secretos. Cuando descarte ese panel, la clave desaparece: solo se conserva un prefijo corto, que es todo lo que la lista podrá mostrarle nuevamente.
La clave nunca se muestra una segunda vez y no puede recuperarse. Si la pierde, revoque esa clave y cree una nueva. No la pegue en un documento compartido, un ticket, un commit o un mensaje de chat.
Solo los roles Propietario y Administrador pueden crear una clave. Cualquier otro rol recibe un error de permisos. Cuando se crea una clave, se envía una alerta de seguridad por correo electrónico a la dirección de quien la creó, así que una inesperada vale la pena investigar inmediatamente.
Los alcances
Se ofrecen siete alcances:
| Alcance | Otorga |
|---|---|
read:sites | Lectura de sus sitios web |
write:sites | Reservado para operaciones de escritura en sitios web |
read:email | Lectura de sus buzones |
write:email | Reservado para operaciones de escritura en buzones |
read:domains | Lectura de sus dominios |
write:domains | Reservado para operaciones de escritura en dominios |
read:billing | Reservado para lectura de datos de facturación |
La API del cliente es de solo lectura hoy en día. Los alcances write: y read:billing pueden seleccionarse en una clave, pero ningún punto de conexión del cliente actualmente los utiliza, así que otorgarlos no cambia nada. Otorgue solo los alcances de lectura que realmente necesita y revise la clave cuando se publiquen los puntos de conexión de escritura.
Usar una clave
Envíe la clave como token portador en el encabezado Authorization.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
Tres puntos de conexión aceptan una clave API del cliente:
| Punto de conexión | Alcance requerido | Devuelve |
|---|---|---|
GET /api/v1/sites | read:sites | Sus sitios web, con dominio, tipo de aplicación y estado |
GET /api/v1/domains | read:domains | Sus dominios, con estado y vencimiento |
GET /api/v1/mailboxes | read:email | Sus buzones |
Una solicitud sin clave, con una clave desconocida o con una clave revocada devuelve 401. Una clave válida sin el alcance correcto devuelve 403 con un mensaje que nombra el alcance que era necesario. Cada llamada exitosa actualiza la marca de tiempo del último uso de la clave.
Consulte con cuidado. Estos puntos de conexión leen datos de cuenta en vivo, y un bucle cerrado contra ellos es indistinguible del abuso. Una vez por minuto es generoso para cualquier cosa que un panel necesite; una vez por hora es generalmente suficiente.
Revisar y revocar claves
La tabla Claves API enumera cada clave activa por Nombre, Prefijo (el comienzo visible de la clave) y Alcances. Haga clic en Revocar al final de una fila para desactivarla.
La revocación tiene efecto inmediato y no hay cuadro de diálogo de confirmación. La siguiente solicitud utilizando esa clave falla con 401. Una clave revocada no puede restaurarse, así que asegúrese de saber qué la está utilizando antes de hacer clic.
Las claves pertenecen a la cuenta, no a la persona que las creó. Eliminar un compañero de equipo de la página Equipo no revoca las claves que crearon. Incorpore una revisión de claves en su proceso de salida: elimine a la persona y luego venga aquí y revoque cualquier cosa que hayan creado.
La creación y revocación de claves se registran en el registro de auditoría bajo las acciones api_key.*, con el actor y la dirección IP de origen.
La caché de compilación remota
La página Desarrollador, en el grupo Avanzado de la barra lateral de configuración, ofrece una Caché de compilación remota. El panel la describe como una forma de "Acelerar compilaciones de Turborepo y Nx compartiendo una caché distribuida en máquinas e canales de CI".
- Vaya a Configuración, luego Desarrollador.
- Haga clic en Activar caché remota.
- Copie el token del panel encabezado "Nuevo token generado. Cópielo ahora, no se mostrará de nuevo".
Luego establezca dos variables de entorno en su configuración de CI o en su .env.local local:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
El ID del equipo es su ID de cuenta de KapsuleHost, que se muestra en las instrucciones de configuración en la misma página.
La página establece su propia compatibilidad: Turborepo 1.x y posterior, Nx 16 y posterior, y cualquier herramienta que implemente el mismo protocolo de caché remota. Los artefactos se almacenan por cuenta y nunca se comparten entre cuentas.
Dos controles adicionales se encuentran en la tarjeta:
- Rotar token emite un nuevo token e invalida el anterior. Cualquier trabajo de CI que aún tenga el token anterior deja de usar la caché, así que rote y actualice sus secretos juntos.
- Desactivar desactiva la caché completamente.
Elegir entre los dos
Resuelven problemas no relacionados y no son intercambiables.
Utilice una clave API cuando algo fuera de KapsuleHost necesite conocer el estado de su cuenta: un panel de estado que enumere sus sitios, un script que le advierta sobre dominios que vencen pronto, una exportación de inventario.
Utilice la caché de compilación remota cuando sus compilaciones son lentas porque cada máquina y cada ejecución de CI reconstruye los mismos paquetes sin cambios. No tiene nada que ver con sus sitios alojados y no lee sus datos de cuenta.
Solución de problemas
Cada solicitud devuelve 401. Confirme que envió el encabezado como Authorization: Bearer <key> con un solo espacio, que la clave no se truncó cuando la copió y que no ha sido revocada. Compare el comienzo de su clave con la columna Prefijo para asegurarse de que está utilizando la clave que cree que está utilizando.
Una solicitud devuelve 403 nombrando un alcance. La clave no tiene ese alcance. Los alcances se fijan cuando se crea la clave, así que cree un reemplazo con los alcances correctos y revoque la anterior.
No puedo ver la tarjeta Claves API. Está en la página Seguridad, no en la página Desarrollador. La página Desarrollador solo contiene la caché de compilación.
El botón Nueva clave no hace nada. Su rol es inferior a Administrador. Pídale al Propietario o a un Administrador.
Las compilaciones no están alcanzando la caché. Verifique que tanto TURBO_TOKEN como TURBO_TEAM estén presentes en el entorno de compilación, que el token no haya sido rotado desde que lo configuró y que la página aún muestre la insignia Activa.
Apareció una clave que no creé. Trátela como un compromiso. Revóquela, luego trabaje a través de Seguridad de cuenta y verifique el registro de auditoría para ver qué más cambió.