---
title: Claves de API y scopes
description: Cómo los clientes crean claves de API (prefijo vk_), eligen scopes, las limitan por IP y vencimiento, y cómo los administradores las revisan y revocan.
url: https://nexcmp.com/es/docs/developers/api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Claves de API y scopes {#api-keys-and-scopes}

> **Ubicación en el portal:** API keys (`/api-keys`). **Ubicación en admin:** Customers › Customers › API keys (`/customers/apikeys`).

## Qué hace {#what-it-does}

Una **API key** permite que un script, un trabajo de CI, la [`cmp` CLI](https://nexcmp.com/es/docs/developers/cmp-cli/) o un asistente de inteligencia artificial ([MCP](https://nexcmp.com/es/docs/developers/mcp/)) llamen a la [REST API](https://nexcmp.com/es/docs/developers/api/) en nombre de un cliente, con solo los permisos (**scopes**) que se le otorgaron. Las claves de cliente comienzan con `vk_`. Pueden leer y administrar servicios, pero **nunca** pueden tocar el dinero ni la cuenta en sí.

## Requisitos {#requirements}

| Elemento | Requisito |
|---|---|
| Cliente | Una sesión iniciada en el portal (una clave no puede crear ni editar otras claves, y un administrador que suplante a un cliente tampoco puede hacerlo). |
| Interruptor | Las claves de API están activadas de forma predeterminada. Si se desactivan, las llamadas responden 401 `api_keys_disabled`. |
| Dependencias | Los scopes de un producto solo aparecen cuando dicho producto está habilitado en el sitio. |

## Crear una clave (cliente) {#create-a-key-customer}

1. Inicie sesión en el portal y abra **API keys**.
2. Haga clic en **Create key**.
3. Complete el formulario:

   | Campo | Regla |
   |---|---|
   | **Nombre de la clave** | Obligatorio, hasta 60 caracteres ("deploy server", "backup script"). |
   | **Qué puede hacer esta clave** | Marque los scopes que necesite — al menos uno. Una clave de solo lectura no debe tener scopes de escritura. Tenga cuidado con los scopes que conllevan costos o eliminan datos. |
   | **Expiry** | Nunca, 30 días, 90 días o 1 año (la API acepta de 1 a 3650 días). |
   | **Permitir solo llamadas desde estas IP** | Una IP o rango CIDR por línea, hasta 20 (IPv4 o IPv6). En blanco significa cualquier IP. Fije la IP de su servidor siempre que sea posible. |

4. Confirme el formulario. La clave se muestra **una sola vez** en una ventana "Key created — shown ONCE". Cópiela y haga clic en **I saved the key**. Solo se almacena un hash SHA-256, por lo que ni siquiera un administrador puede volver a verla; si la pierde, revóquela y cree una nueva.
5. El portal también muestra un comando `curl` listo para probar la clave.


Una clave tiene el aspecto de `vk_` seguido de una cadena aleatoria larga. La lista solo muestra los primeros caracteres (por ejemplo, `vk_a1b2c3d4`), los scopes, el vencimiento, el último uso, el recuento de solicitudes y el estado (*Active*, *Expired*, *Revoked*).

### Editar, revocar, auditar {#edit-revoke-audit}

- **Edit** modifica el nombre, los scopes, las IP permitidas y la expiración. No está permitido durante una sesión de suplantación.
- **Revoke** desactiva la clave de inmediato y no se puede deshacer. La fila se conserva para que su registro de uso permanezca disponible.
- **Key usage log** muestra los comandos de escritura y cada error de los últimos 60 días: hora, solicitud, clave, resultado e IP de origen.
- Una cuenta puede tener como máximo **10 claves activas** de forma predeterminada.
- Las claves creadas a través del inicio de sesión de CLI o MCP aparecen en **Connected apps & devices** y pueden revocarse allí.

## Scopes {#scopes}

Los nombres de los scopes tienen el formato `area:action`. Cuáles se ofrecen depende de los productos que tenga habilitados.

| Scope | Permite |
|---|---|
| `catalog:read` | Leer planes y el catálogo. |
| `vm:read` | Leer VM, métricas y facturas de VM. |
| `vm:write` | Acciones de energía, cambios menores, firewall, Snapshots rápidos. |
| `vm:create` | **Crear VM (tiene coste).** |
| `vm:plan` | **Cambiar de plan o redimensionar (tiene coste).** |
| `vm:destroy` | **Eliminar VM.** |
| `vm:restore` | **Restaurar una VM desde un Snapshot (sobrescribe el disco).** |
| `vm:console` | Abrir tickets de consola VNC. |
| `sshkey:read`, `sshkey:write` | Leer, añadir y eliminar SSH Keys. |
| `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | Volúmenes de datos (crear y ampliar tiene coste; destruir ocasiona pérdida de datos). |
| `backup:read`, `backup:write`, `backup:restore` | Backups (la restauración sobrescribe el disco). |
| `billing:read` | Wallet, facturas, historial de pagos — **solo lectura**. |
| `bandwidth:buy` | **Comprar un complemento de ancho de banda (tiene coste).** |
| `account:read`, `account:write` | Perfil, resumen, actividad, notificaciones; `account:write` solo marca las notificaciones como leídas. |
| `apikey:read` | Listar las claves de la cuenta y el registro de uso (no permite crear, editar ni revocar). |
| `apikey:self` | Implícito en cada clave: inspeccionar la clave que realiza la llamada (`GET /v1/apikeys/self`). |
| `ticket:read`, `ticket:write` | Tickets de soporte. |
| `aff:read`, `transfer:read` | Programa de afiliados y transferencias de servicios — solo lectura. |
| `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes (crear y escalar tiene coste; kubeconfig es cluster-admin). |
| `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | Private Cloud. |
| `image:read`, `image:write` | Imágenes de SO e ISO (el almacenamiento se factura por horas). |
| `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage (el secreto S3 se muestra una sola vez). |
| `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPN y proxy IPv6 (los detalles de conexión incluyen contraseñas de proxy). |
| `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | Servidores dedicados (crear realiza pedidos desde la wallet; destruir reinstala el SO). |
| `shield:read`, `shield:write`, `shield:agent` | DDoS Shield, solo cuando ese módulo está habilitado. |

Una llamada fuera de los scopes de la clave responde **403 `scope_required`**; una ruta a la que ninguna clave puede llamar responde **403 `endpoint_not_public`**.

### Lo que una clave nunca puede hacer {#what-a-key-can-never-do}

Ningún scope permite: recargar o retirar fondos, cambiar tarjetas o la recarga automática, cambiar la contraseña, el correo electrónico o 2FA, eliminar la cuenta, ni crear, editar o revocar otras claves. Estas acciones siempre requieren una sesión iniciada en el navegador. Incluso si una clave se filtra, no puede acceder a los fondos ni a la cuenta del cliente.

## Reglas en las que puede confiar {#rules-you-can-rely-on}

| Regla | Detalle |
|---|---|
| Vinculada al sitio | Una clave funciona únicamente en el sitio (dominio) donde se creó. |
| Límites de tasa | Por clave y por cuenta: 120 y 300 solicitudes por minuto de forma predeterminada. |
| Idempotencia | Las operaciones que tienen coste o no se pueden repetir requieren un encabezado `Idempotency-Key`. |
| Cuotas | Una clave está sujeta a las mismas [cuotas](https://nexcmp.com/es/docs/billing/quotas/) que el cliente. |
| Cuenta bloqueada | Las claves de un cliente bloqueado dejan de funcionar (403 `account_blocked`). |
| Auditoría | La revocación por parte de un administrador se registra en el log de auditoría de administración. |

## Vista de administrador {#administrator-view}

1. Abra **Customers › API keys** (`/customers/apikeys`). La tabla muestra el nombre de la clave y sus primeros caracteres, propietario, scopes, estado, último uso (hora, número de solicitudes, IP) y vencimiento.
2. Filtre por sitio si tiene revendedores. Busque por nombre, ID o inicio de clave.
3. Haga clic en **Revoke** para anular una clave activa, o en **Log** para ver su uso.
4. Los administradores **ven y revocan** claves, pero no pueden leerlas ni crearlas para los clientes.

![Lista de administrador de claves de API de clientes con scopes, estado, último uso y el botón Revoke](https://nexcmp.com/es/docs/images/developers/api-keys-02-admin.webp)

## Verificación {#verify}

1. Cree una clave solo con el scope `vm:read`.
2. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` devuelve la lista de VM.
3. `curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX"` responde 403 `scope_required`.
4. Revoque la clave; la primera llamada ahora responde 401 `key_revoked`.

## Límites y notas {#limits-notes}

- La clave no se volverá a mostrar. Trátela como una contraseña y guárdela en un gestor de secretos o en un secreto de CI.
- Priorice una clave por script, scopes mínimos, una expiración corta y una lista de IP permitidas; rótela creando una clave nueva y revocando la anterior.
- Las claves de inicio de sesión de dispositivo (CLI, MCP) vencen por defecto a los 90 días.
- Los recursos eliminados o transferidos no se ven afectados al revocar una clave.

## Resolución de problemas {#troubleshooting}

| Síntoma | Causa | Solución |
|---|---|---|
| Error `too_many_keys` (422) | Se alcanzó el límite de claves activas (10 por defecto) | Revoque una clave antigua. |
| Error `invalid_argument`: no se seleccionó ningún scope | Ningún scope marcado | Marque al menos un scope. |
| Error `invalid_argument` en IP permitidas | Una entrada no es una IP o rango, longitud de prefijo incorrecta o más de 20 entradas | Una IP o CIDR por línea, por ejemplo `203.0.113.0/24`. |
| Se rechaza la creación durante la suplantación | `impersonate_forbidden` | Solicite al cliente que cree la clave. |
| 401 `key_expired` | Fecha de vencimiento superada | Cree una nueva clave. |
| 401 `key_ip_denied` | La IP de origen no está en la lista de permitidas | Añada la IP o borre la lista. |
| 401 `api_keys_disabled` | Función desactivada | Consulte a su administrador (ajuste `api_keys_enabled`). |