Cuenta
Claves API y Acceso de Desarrollador
Kapsule gives you two developer surfaces: scoped API keys for reading your account programmatically, and a remote build cache that speeds up Turborepo and Nx builds on your own machines and CI…
Kapsule le ofrece dos superficies para desarrolladores: claves API con ámbito 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 de forma predeterminada. 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 la clave (por ejemplo, Mi script de automatización)". El nombre es solo para usted, por lo que debe indicar dónde se utilizará la clave.
- Haga clic en los chips de ámbito para seleccionar qué puede hacer la clave. Tres ámbitos de lectura están preseleccionados:
read:sites,read:emailyread:domains. Haga clic en un chip para agregarlo o quitarlo. - Haga clic en Crear.
La clave completa aparece una vez, en un panel verde titulado "Copiar ahora". Cópiela directamente en su almacén de secretos. Cuando cierre ese panel, la clave desaparece: solo se mantiene un prefijo corto, que es todo lo que la lista puede mostrarle nuevamente.
La clave nunca se muestra una segunda vez y no se puede recuperar. Si la pierde, revoque esa clave y cree una nueva. No la pegue en un documento compartido, un ticket, una confirmación 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 un correo electrónico de alerta de seguridad a la dirección de quien la creó, por lo que si recibe uno inesperado, vale la pena investigar inmediatamente.
Los ámbitos
Se ofrecen siete ámbitos:
| Ámbito | 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 de cliente es de solo lectura hoy. Los ámbitos write: y read:billing se pueden seleccionar en una clave, pero ningún extremo de cliente los consume actualmente, por lo que otorgarlos no cambia nada. Otorgue solo los ámbitos de lectura que realmente necesite y revise la clave cuando se lancen los extremos de escritura.
Usar una clave
Envíe la clave como token de portador en el encabezado Authorization.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
Tres extremos aceptan una clave de API de cliente:
| Extremo | Ámbito 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, una clave desconocida o una clave revocada devuelve 401. Una clave válida sin el ámbito correcto devuelve 403 con un mensaje que menciona el ámbito que se necesitaba. Cada llamada exitosa actualiza la marca de tiempo de último uso de la clave.
Consulte con moderación. Estos extremos leen datos de cuenta activos, y un bucle ajustado contra ellos es indistinguible del abuso. Una vez por minuto es generoso para cualquier cosa que un panel de control necesite; una vez por hora suele ser más que suficiente.
Revisar y revocar claves
La tabla de claves API enumera cada clave activa por Nombre, Prefijo (el comienzo visible de la clave) y Ámbitos. Haga clic en Revocar al final de una fila para eliminarla.
La revocación entra en vigor inmediatamente y no hay un diálogo de confirmación. La siguiente solicitud que utiliza esa clave falla con 401. Una clave revocada no se puede restaurar, 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 del equipo no revoca las claves que creó. Incorpore una revisión de claves en su proceso de desvinculación: elimine a la persona y luego venga aquí y revoque cualquier cosa que haya 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 del carril 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 entre máquinas y canalizaciones de CI".
- Vaya a Configuración, luego Desarrollador.
- Haga clic en Habilitar caché remota.
- Copie el token del panel titulado "Nuevo token generado. Cópielo ahora, no se mostrará nuevamente".
Luego establezca dos variables de entorno en su configuración de CI o .env.local local:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
El ID del equipo es su ID de cuenta de Kapsule, que se muestra en las instrucciones de configuración en la misma página.
La página declara 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 siga teniendo el token anterior deja de usar la caché, así que rote y actualice sus secretos juntos.
- Deshabilitar desactiva la caché completamente.
Elegir entre los dos
Resuelven problemas no relacionados y no son intercambiables.
Utilice una clave API cuando algo fuera de Kapsule necesita conocer el estado de su cuenta: un tablero de estado que enumera sus sitios, un script que le advierte 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 recompilan los mismos paquetes sin cambios. No tiene nada que ver con sus sitios alojados y no lee los datos de su cuenta.
Si va a implementar desde Git en lugar de llamar a una API, considere Kapsule Orbit. Compila y envía desde su repositorio directamente, con almacenamiento en caché de compilación manejado para usted.
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á usando.
Una solicitud devuelve 403 mencionando un ámbito. La clave no tiene ese ámbito. Los ámbitos se fijan cuando se crea la clave, así que cree una de reemplazo con los ámbitos correctos y revoque la antigua.
No puedo ver la tarjeta de claves API. Se encuentra 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 está por debajo de Administrador. Pida al Propietario o a un Administrador.
Las compilaciones no están llegando a la caché. Compruebe que tanto TURBO_TOKEN como TURBO_TEAM están presentes en el entorno de compilación, que el token no se haya rotado desde que lo estableció y que la página aún muestre la insignia Activo.
Apareció una clave que no creé. Trátela como un compromiso. Revóquela, luego revise Seguridad de la cuenta y compruebe el registro de auditoría para ver qué más cambió.