--- title: Claves API de admin description: Cree y revoque claves ak_ de admin para scripts y AI Agent: los 8 scopes, expiración, rangos IP, rate limit, lo que nunca pueden hacer y códigos de error. url: https://nexcmp.com/es/docs/configure-with-ai/admin-api-keys/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Claves API de admin {#admin-api-keys} > **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 {#what-it-does} 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. ::: info 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](https://nexcmp.com/es/docs/developers/api-keys/)). 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 {#requirements} | 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 {#create-a-key} 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](#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). ![Diálogo de nueva clave con nombre, casillas de verificación de scope, expiración y rango IP completados](https://nexcmp.com/es/docs/images/configure-with-ai/admin-api-keys-01-create.webp) ![Diálogo que muestra la nueva clave una sola vez con un botón Copiar y una advertencia](https://nexcmp.com/es/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp) ## Scopes {#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. | ::: tip 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 {#revoke-a-key} 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 {#what-a-key-can-never-do} 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 {#actions-that-need-your-confirmation} Estas solo se ejecutan tras aprobar una vista previa (consulte [Confirmación en dos pasos](#two-step-confirmation)): - 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 {#two-step-confirmation} 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: `. 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 {#rate-limit-and-ip-rules} - 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 {#activity-log} 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:/`. ![Pestaña Activity que muestra las llamadas con estado, cliente, herramienta e IP](https://nexcmp.com/es/docs/images/configure-with-ai/admin-api-keys-03-activity.webp) ## Verificación {#verify} Pruebe una clave de solo lectura desde cualquier máquina que esté dentro del rango de IP: ```bash 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: ```bash 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](https://nexcmp.com/es/docs/configure-with-ai/mcp-admin/). ## Errores {#errors} 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 {#limits-notes} - 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](https://nexcmp.com/es/docs/configure-with-ai/oauth-connectors/)).