Claves API de admin

Ubicación en el admin: System › Settings › API & AI agents (/agent/keys), pestaña API keys. La misma página incluye las pestañas Connect an AI, Connected apps y Activity.

Qué hace

Una clave API de admin (prefijo ak_) permite que un cliente de IA o un script gestione su panel con los permisos exactos asignados. Funciona en la API de admin en /v1/admin/ y en el endpoint MCP de admin /mcp/admin. No funciona en ningún otro lugar.

No es lo mismo que las claves de cliente

Los clientes crean claves que comienzan con vk_ en el portal de cliente (API keys and scopes). Esas solo acceden a la API de cliente y a /mcp. Se rechaza una clave ak_ en la API de cliente, y se rechaza una clave vk_ en la API de admin.

Requisitos

Elemento	Requisito
Rol	Debe haber iniciado sesión en el admin. Las claves no pueden crear otras claves.
Demo	En un panel de demostración, la página es de solo lectura: no se puede crear ni revocar ninguna clave.
Accesibilidad	El cliente debe alcanzar https://cloud.example.com/mcp/admin o /v1/admin/... en su panel (compruebe su firewall si utiliza restricciones de IP).

Crear una clave

1. Abra System › Settings › API & AI agents y permanezca en la pestaña API keys.

2. Haga clic en Create new key.

3. Complete el formulario:

   Campo	Reglas
   Nombre	Hasta 60 caracteres, por ejemplo "Claude Code en mi portátil".
   Scopes	Marque al menos uno. Consulte Scopes. Empiece solo con admin:read.
   Expiración	1, 7, 30, 60 o 90 días. Predeterminado: 30. Máximo: 90. No se puede crear una clave sin expiración.
   Rangos IP (opcional)	Una dirección IPv4 o IPv6 o CIDR por línea, por ejemplo 203.0.113.0/24 o 2001:db8::/48. Máximo 32. Déjelo en blanco para permitir cualquier IP.
   Llamadas por minuto	1 a 6000. Predeterminado: 120.

4. Haga clic en Create key. Un cuadro muestra la clave una sola vez, por ejemplo ak_XXXX. Cópiela ahora: NexCMP almacena solo un hash y nunca podrá volver a mostrarla.

5. Haga clic en I have saved the key. Abra la pestaña Connect an AI para obtener comandos listos para pegar que ya contienen la clave recién creada (solo en esta página, hasta que la recargue).

Scopes

Una clave solo puede utilizar las herramientas y endpoints que sus scopes permitan. Los scopes de escritura no incluyen acceso de lectura: una clave que deba leer y escribir también necesita admin:read.

Scope	Lo que permite
admin:read	Lectura de configuración, catálogo, clientes, facturación y registros. Los secretos nunca se devuelven.
catalog:write	Planes, plantillas de SO, cuotas, códigos de descuento.
infra:write	Fuentes de infraestructura (CloudStack, Proxmox), zonas, servidores.
billing:write	Pasarelas de pago, divisa, facturas, saldos. Las acciones monetarias requieren confirmación.
customers:write	Clientes y revendedores.
settings:write	Configuración general, personalización de marca, correo electrónico, páginas legales, módulos y notificaciones.
ai:write	El proveedor de IA y las funciones de IA.
secrets:write	Escribir contraseñas y claves de API. Se pueden configurar, pero nunca volver a leer.

Configurar un secreto requiere dos ámbitos

Cualquier llamada que incluya una contraseña, clave de API o valor de token (una contraseña SMTP, una clave de pago, un token de bot de Telegram, una clave de proveedor de IA, credenciales de CloudStack o Proxmox) requiere secrets:write y el ámbito del área (por ejemplo, settings:write para SMTP). Si prefiere escribir los secretos manualmente, desactive secrets:write e introdúzcalos en el panel de administración.

Revocar una clave

1. Localice la clave en la tabla (estado Active, Expired o Revoked; Last used muestra la fecha/hora y el cliente).
2. Haga clic en Revoke y confirme.

La clave dejará de funcionar de inmediato. La revocación es permanente; cree una nueva clave si vuelve a necesitarla.

Lo que una clave nunca puede hacer

Una clave nunca puede acceder a estas áreas, independientemente de sus ámbitos. Requieren haber iniciado sesión en el panel de administración.

• Crear o modificar usuarios administradores, 2FA y seguridad de inicio de sesión, sesiones de administración y tokens de API de administración.
• Crear, listar o revocar claves de administrador, conexiones OAuth y cuentas de IA, o utilizar la AI Console.
• Hacer copias de seguridad o restaurar el panel, actualizarlo o cambiar su licencia.
• Iniciar sesión como cliente o revendedor, abrir la consola de un cliente, consultar credenciales de VM o kubeconfig, configurar SSH Keys, o enviar o restablecer contraseñas.
• Modificar módulos de red y enrutamiento (BGP, FRR, RTBH, XDP, interfaces, rutas estáticas y de políticas, NAT) o agentes externos e integración del portal. Son de solo lectura.
• Modificar parámetros como demo_*, admin_*, listas de hosts, passkey, reautenticación y secretos de captcha.

Todo lo que no esté cubierto por una regla está cerrado de forma predeterminada para escrituras, y se puede consultar con admin:read para lecturas.

Acciones que requieren su confirmación

Estas solo se ejecutan tras aprobar una vista previa (consulte Confirmación en dos pasos):

• Modificar el saldo de un cliente o la billetera de un revendedor, realizar pagos, registros de facturación, el tipo de cambio.
• Modificar precios (precios de planes, creación masiva de planes, precios de imágenes y almacenamiento) y crear códigos de descuento o de saldo.
• Guardar las credenciales de la pasarela de pago o la conexión de CloudStack.
• Eliminar cualquier elemento, bloquear o eliminar a un cliente, cambiar los límites de un cliente, suspender o cerrar a un revendedor.
• Realizar acciones en los servidores de los clientes o crear un servidor de pago para un cliente.
• Modificar conmutadores globales del sitio, ajustes de seguridad de inicio de sesión o ajustes de pago a través de la configuración general.

Confirmación en dos pasos

Cuando una llamada requiere confirmación, aún no se modifica nada. La respuesta es HTTP 428 con confirm_required, un confirm_token, un preview (método, ruta, motivo, los nuevos valores y, si están disponibles, los valores actuales) y expires_in: 300.

1. El cliente le muestra la vista previa.
2. Tras su aprobación, repite la misma solicitud (mismo método, ruta y cuerpo) con el encabezado X-Confirm-Token: <confirm_token>. Las herramientas de MCP toman el argumento confirm_token en su lugar.
3. El token funciona una sola vez y expira transcurridos 5 minutos.

Las claves creadas en el panel de administración para AI Chat solo se pueden confirmar en pantalla: la respuesta indica confirm_in: "ui" y aparece una tarjeta de confirmación en el panel de administración. La IA no puede aprobarla.

Límites de frecuencia y reglas de IP

• Al superar el límite por minuto, una llamada devuelve rate_limited (HTTP 429) con Retry-After: 60.
• Si se configuran rangos de IP, las llamadas desde cualquier otra dirección devuelven ip_not_allowed (HTTP 403).

Registro de actividad

La pestaña Activity enumera cada llamada realizada con una clave, de la más reciente a la más antigua: hora, clave, cliente, cómo llegó (http, mcp, chat, cli, confirm, preview), método y ruta, herramienta, estado HTTP, IP y los detalles (enmascarados). Puede buscar por ruta, herramienta o nombre de clave, mostrar solo errores (HTTP 400 y superior) o solo llamadas en espera de confirmación (428 y superior), y limitar el período a la última hora, 24 horas o 7 días. NexCMP conserva las 200,000 entradas más recientes. Los cambios realizados mediante una clave también aparecen en Logs › Admin actions con el nombre ak:<admin>/<key name>.

Verificación

Pruebe una clave de solo lectura desde cualquier máquina que esté dentro del rango de IP:

curl -s https://cloud.example.com/v1/admin/agent/tools \
  -H "Authorization: Bearer ak_XXXX"

Obtendrá una lista JSON de las herramientas que permiten sus scopes. Ejecute una:

curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \
  -H "Authorization: Bearer ak_XXXX" \
  -H "Content-Type: application/json" -d '{}'

La hora en Last used de la clave se actualiza y la llamada aparece en Activity. La lista completa de herramientas y una descripción de OpenAPI (/v1/admin/openapi.json) se detallan en Conectar un cliente de IA.

Errores

Los errores se devuelven en JSON: {"error": {"code": "...", "message": "..."}}.

HTTP	code	Significado	Solución
401	invalid_key	La clave falta, es inválida o es desconocida. También se devuelve cuando se utiliza una clave ak_ en una ruta que no es de administración.	Compruebe la clave; utilícela solo en /v1/admin/ y /mcp/admin.
401	key_expired	La clave ha caducado.	Cree una nueva clave.
401	key_revoked	La clave fue revocada.	Cree una nueva clave.
403	ip_not_allowed	La IP de origen está fuera de los rangos de IP de la clave.	Llame desde una IP permitida o cree una clave con el rango correcto.
403	local_only_key	Se utilizó desde otra máquina una clave creada para AI Chat o la CLI del servidor.	Estas claves solo funcionan en el propio servidor del panel.
403	insufficient_scope	A la clave le falta un scope; la respuesta incluye required_scope.	Cree una clave con ese scope.
403	forbidden_for_keys	El endpoint, o la configuración que intentó cambiar, no admite claves.	Hágalo en el admin.
403	demo_read_only	El panel está en modo de demostración y la llamada es de escritura.	Utilice un panel que no sea de demostración.
403	confirm_in_ui	Esta acción debe confirmarse en pantalla en el admin.	Apruebe la tarjeta de confirmación.
428	confirm_required	Hay una vista previa lista; no se aplicó ningún cambio. Incluye confirm_token.	Muestre la vista previa y luego repita con X-Confirm-Token.
409	confirm_expired	El token tiene más de 5 minutos de antigüedad.	Envíe la solicitud de nuevo para obtener una nueva vista previa.
409	confirm_mismatch	El token pertenece a una solicitud diferente (el método, la ruta o el cuerpo difieren).	Repita exactamente la misma solicitud.
409	confirm_invalid	Token desconocido o ya utilizado.	Envíe la solicitud de nuevo para obtener una nueva vista previa.
429	rate_limited	Demasiadas llamadas en este minuto.	Espere a Retry-After.
400	invalid_path	La ruta contiene secuencias prohibidas.	Utilice una ruta simple.
413	too_large	El cuerpo supera los 10 MB.	Envíe menos datos.
400	invalid_argument	Falta un argumento de la herramienta, es desconocido o tiene un tipo incorrecto; el mensaje lo especifica.	Corrija el argumento.

Límites y notas

• Mantenga las claves con vigencia corta y permisos limitados. Se recomienda una clave por cliente para poder revocar solo una si es necesario.
• Una clave es tan potente como sus scopes. secrets:write más billing:write es la combinación más delicada; las acciones relacionadas con dinero se detienen siempre en una vista previa.
• Las claves creadas automáticamente (para AI Chat o la CLI del servidor) duran solo unos minutos y funcionan únicamente desde el servidor del panel.
• Para desconectar de inmediato un cliente de IA, revoque su clave. Las conexiones OAuth se revocan en la pestaña Connected apps (OAuth connectors).