# Claves de API

Source : https://webgune.cloud/es-es/docs/cles-api · Mis à jour le 2026-10-27

# Claves de API

Las claves de API (prefijo `wgk_`) dan un acceso programático a tu cuenta: [CLI](/docs/cli), [extensión de VS Code](/docs/extension-vscode), scripts de CI, o llamadas directas a la [API](/docs/reference-api).

## Crear una clave

**Dashboard → Desarrolladores → Claves de API → Nueva clave**:

| Ajuste | Función |
|---------|------|
| **Nombre** | Para identificarla («CI producción», «laptop personal»…) |
| **Scopes** | Lo que la clave tiene derecho a hacer (ver más abajo) |
| **Límite de tasa** | Peticiones/minuto permitidas (60 por defecto) |
| **Expiración** | Opcional, recomendada para las claves de CI |

La clave completa se muestra **una sola vez**, en la creación. Guárdala en un gestor de secretos; solo su firma truncada queda visible después.

## Los scopes

Un scope sigue el formato `recurso:acción`:

```
projects:read      # listar y leer los proyectos
services:write     # desplegar, reiniciar, configurar
services:*         # todo sobre los servicios
billing:read       # leer facturas y suscripción
*                  # todos los derechos (evitar fuera de pruebas)
```

**Principio del mínimo privilegio**: una clave de CI que solo despliega solo necesita `services:write`. Una clave de monitoring, `projects:read`. Crea varias claves estrechas en lugar de una sola amplia.

## Usar una clave

```bash
curl https://api.webgune.cloud/api/v1/projects \
  -H "Authorization: Bearer wgk_xxxxxxxxxxxx"
```

Una clave actúa **en nombre de su propietario**: hereda tus [roles en cada proyecto](/docs/roles-permissions), nunca más. Sus scopes solo pueden restringir, no ampliar.

## Actuar por un subcliente (revendedores)

Una clave creada con **Actuar por los subclientes** activado (reservado al propietario de una organización) puede actuar en nombre de uno de sus subclientes, añadiendo la cabecera `X-Act-As-User-Id`:

```bash
curl https://api.webgune.cloud/api/v1/projects \
  -H "Authorization: Bearer wgk_xxxxxxxxxxxx" \
  -H "X-Act-As-User-Id: usr_del_subcliente"
```

El subcliente objetivo debe pertenecer a la misma organización, de lo contrario la petición falla como si el recurso no existiera (404). Los scopes de la clave se siguen aplicando. Actuar por un subcliente no otorga más derechos de los que la clave ya tiene.

## Registro de auditoría

Cada clave tiene su propio registro, consultable desde **Dashboard → Desarrolladores → Claves de API → icono de registro**, o mediante `GET /api/v1/api-keys/:id/audit-log`: las últimas 100 llamadas (método, ruta, código de retorno, duración, y si la petición se hizo en nombre de un subcliente). Útil para detectar una clave que se filtra o un script que falla silenciosamente.

## Límites

- **WebSockets excluidos**: los flujos en tiempo real (logs en directo, colaboración) requieren una sesión de navegador: una clave de API no puede conectarse a ellos. El snapshot REST de los logs sigue siendo accesible.
- Una clave **expirada o revocada** se rechaza de inmediato; revoca sin dudar toda clave potencialmente expuesta (la revocación es instantánea y sin efecto sobre tus otras claves).
- Cada clave tiene **su propio** límite de tasa: un script descontrolado no agota la cuota de las demás.