Claves de API y scopes

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

Qué hace

Una API key permite que un script, un trabajo de CI, la cmp CLI o un asistente de inteligencia artificial (MCP) llamen a la REST 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

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)

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

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

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

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

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.

Verificación

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

• 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

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