# Claves API y Acceso para Desarrolladores

Source: https://support.kapsulehost.com/es-es/developer-api-access

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**.

![Tarjeta Claves API en la configuración de seguridad de KPanel con los chips de alcance visibles](https://support.kapsulehost.com/help/screenshots/developer-api-access.8d15f634.webp)

1. Vaya a **Configuración**, luego **Seguridad**.
2. Desplácese hasta **Claves API** y haga clic en **Nueva clave**.
3. 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.
4. Haga clic en los chips de alcance para seleccionar qué puede hacer la clave. Tres alcances de lectura están preseleccionados: `read:sites`, `read:email` y `read:domains`. Haga clic en un chip para añadirlo o eliminarlo.
5. 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.

> **Warning:** 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 |

> **Note:** 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`.

```sh
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.

> **Tip:** 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.

> **Important:** 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](https://support.kapsulehost.com/es-es/account-team-members) 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](https://support.kapsulehost.com/es-es/account-audit-log) 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".

1. Vaya a **Configuración**, luego **Desarrollador**.
2. Haga clic en **Activar caché remota**.
3. 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:

```sh
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](https://support.kapsulehost.com/es-es/account-security) y verifique [el registro de auditoría](https://support.kapsulehost.com/es-es/account-audit-log) para ver qué más cambió.