--- title: Chiavi API amministrative description: Crea e revoca chiavi admin ak_ per AI Agent e script: otto scope, scadenza, range IP, rate limit, cosa non possono mai fare e tutti i codici di errore. url: https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Chiavi API amministrative {#admin-api-keys} > **Dove nel pannello admin:** System › Settings › API & AI agents (`/agent/keys`), scheda **API keys**. La stessa pagina include le schede **Connect an AI**, **Connected apps** e **Activity**. ## Descrizione {#what-it-does} Una chiave API amministrativa (prefisso `ak_`) consente a un client IA o a uno script di gestire il tuo pannello con esattamente i permessi assegnati. Funziona sull'API admin in `/v1/admin/` e sull'endpoint MCP admin in `/mcp/admin`. Non funziona altrove. ::: info Diverse dalle chiavi cliente I clienti creano chiavi che iniziano con `vk_` nel portale clienti ([API keys and scopes](https://nexcmp.com/it/docs/developers/api-keys/)). Queste raggiungono solo l'API cliente e `/mcp`. Una chiave `ak_` viene rifiutata sull'API cliente e una chiave `vk_` viene rifiutata sull'API admin. ::: ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Ruolo | Devi aver effettuato l'accesso come amministratore. Le chiavi non possono crearne altre. | | Demo | Su un pannello demo la pagina è di sola lettura: non è possibile creare o revocare alcuna chiave. | | Raggiungibilità | Il client deve raggiungere `https://cloud.example.com/mcp/admin` o `/v1/admin/...` sul tuo pannello (controlla il firewall se utilizzi restrizioni IP). | ## Crea una chiave {#create-a-key} 1. Apri **System › Settings › API & AI agents** e rimani sulla scheda **API keys**. 2. Fai clic su **Create new key**. 3. Compila il modulo: | Campo | Regole | |---|---| | Name | Fino a 60 caratteri, ad esempio "Claude Code sul mio portale". | | Ambiti | Seleziona almeno uno. Vedi [Scopes](#scopes). Inizia solo con `admin:read`. | | Scadenza | 1, 7, 30, 60 o 90 giorni. Predefinito 30. Massimo 90. Non è possibile creare una chiave senza scadenza. | | Intervalli IP (opzionale) | Un indirizzo IPv4 o IPv6 oppure CIDR per riga, ad esempio `203.0.113.0/24` o `2001:db8::/48`. Al massimo 32. Lascia vuoto per consentire qualsiasi IP. | | Chiamate al minuto | Da 1 a 6000. Predefinito 120. | 4. Fai clic su **Create key**. Un riquadro mostra la chiave una sola volta, ad esempio `ak_XXXX`. **Copia ora**: NexCMP memorizza solo un hash e non potrà più mostrarla. 5. Fai clic su **I have saved the key**. Apri la scheda **Connect an AI** per ottenere comandi pronti all'uso che contengono già la chiave appena creata (solo su questa pagina, fino al ricaricamento). ![Finestra di dialogo Nuova chiave con nome, caselle di ambito, scadenza e intervallo IP compilati](https://nexcmp.com/it/docs/images/configure-with-ai/admin-api-keys-01-create.webp) ![Finestra di dialogo che mostra la nuova chiave una volta con un pulsante Copia e un avviso](https://nexcmp.com/it/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp) ## Ambiti {#scopes} Una chiave può utilizzare solo gli strumenti e gli endpoint consentiti dai suoi ambiti. Gli ambiti di scrittura non includono l'accesso in lettura: una chiave che deve leggere e scrivere necessita anche di `admin:read`. | Ambito | Cosa consente | |---|---| | `admin:read` | Leggere impostazioni, catalogo, clienti, fatturazione e log. I dati sensibili non vengono mai restituiti. | | `catalog:write` | Piani, template OS, quote, codici sconto. | | `infra:write` | Origini infrastruttura (CloudStack, Proxmox), zone, server. | | `billing:write` | Gateway di pagamento, valuta, fatture, saldi. Le azioni monetarie richiedono conferma. | | `customers:write` | Clienti e rivenditori. | | `settings:write` | Impostazioni generali, branding, email, pagine legali, moduli, notifiche. | | `ai:write` | Il provider IA e le funzioni IA. | | `secrets:write` | Scrivi password e chiavi API. Possono essere impostate ma mai lette. | ::: tip L'impostazione di un segreto richiede due ambiti Qualsiasi chiamata che trasporti una password, una chiave API o un valore di token (una password SMTP, una chiave di pagamento, un token bot di Telegram, una chiave del provider IA, credenziali CloudStack o Proxmox) richiede `secrets:write` **e** l'ambito dell'area (ad esempio `settings:write` per SMTP). Se preferisci digitare tu stesso i segreti, lascia disattivato `secrets:write` e inseriscili nell'admin. ::: ## Revoca una chiave {#revoke-a-key} 1. Trova la chiave nella tabella (stato **Active**, **Expired** o **Revoked**; **Last used** mostra l'ora e il client). 2. Fai clic su **Revoke** e conferma. La chiave smette di funzionare immediatamente. La revoca è permanente; creane una nuova se ti serve di nuovo. ## Cosa una chiave non può mai fare {#what-a-key-can-never-do} Una chiave non può mai raggiungere queste aree, indipendentemente dai suoi ambiti. Richiedono l'accesso come amministratore. - Crea o modifica utenti amministratori, 2FA e sicurezza di accesso, sessioni admin e token API admin. - Crea, elenca o revoca chiavi admin, connessioni OAuth e account IA, oppure usa la Console IA. - Esegui il backup o il ripristino del pannello, aggiornalo o modifiane la licenza. - Accedi come cliente o rivenditore, apri la console di un cliente, leggi credenziali di VM o kubeconfig, imposta chiavi SSH oppure invia o reimposta password. - Modifica i moduli di rete e routing (BGP, FRR, RTBH, XDP, interfacce, route statiche e di policy, NAT) o agenti esterni e integrazione del portale. Questi sono di sola lettura. - Modifica impostazioni quali `demo_*`, `admin_*`, elenchi host, passkey, riautenticazione e segreti captcha. Tutto ciò che non è coperto da una regola è chiuso per impostazione predefinita per le scritture e leggibile con `admin:read` per le letture. ### Azioni che richiedono la tua conferma {#actions-that-need-your-confirmation} Queste vanno a buon fine solo dopo aver approvato un'anteprima (vedi [Two-step confirmation](#two-step-confirmation)): - Modifica del saldo di un cliente o del portafoglio di un rivenditore, erogazione di denaro, registri di fatturazione, tasso di cambio. - Modifica dei prezzi (prezzi dei piani, creazione massiva di piani, prezzi di immagini e storage) e creazione di codici sconto o promozionali. - Salvataggio delle credenziali del gateway di pagamento o della connessione CloudStack. - Eliminazione di qualsiasi elemento, blocco o eliminazione di un cliente, modifica dei limiti di un cliente, sospensione o chiusura di un rivenditore. - Intervento sui server dei clienti o creazione di un server a pagamento per un cliente. - Modifica di interruttori globali del sito, impostazioni di sicurezza dell'accesso o impostazioni di pagamento tramite le impostazioni generali. ## Conferma in due passaggi {#two-step-confirmation} Quando una chiamata richiede una conferma, nulla cambia ancora. La risposta è HTTP **428** con `confirm_required`, un `confirm_token`, un `preview` (metodo, percorso, motivo, i nuovi valori e, quando disponibili, i valori correnti) e `expires_in: 300`. 1. Il client ti mostra l'anteprima. 2. Dopo l'approvazione, ripete la **stessa** richiesta (stesso metodo, percorso e corpo) con l'intestazione `X-Confirm-Token: `. Gli strumenti MCP accettano invece l'argomento `confirm_token`. 3. Il token funziona una volta e scade dopo 5 minuti. Le chiavi create nell'area amministrativa per AI Chat possono essere confermate solo a schermo: la risposta indica `confirm_in: "ui"` e compare una scheda di conferma nell'amministrazione. L'intelligenza artificiale non può approvarla. ## Limiti di frequenza e regole IP {#rate-limit-and-ip-rules} - Oltre il limite al minuto, una chiamata restituisce `rate_limited` (HTTP 429) con `Retry-After: 60`. - Con intervalli IP impostati, le chiamate da qualsiasi altro indirizzo restituiscono `ip_not_allowed` (HTTP 403). ## Registro attività {#activity-log} La scheda **Activity** elenca tutte le chiamate effettuate con una chiave, dalla più recente: ora, chiave, cliente, modalità di arrivo (`http`, `mcp`, `chat`, `cli`, `confirm`, `preview`), metodo e percorso, strumento, stato HTTP, IP e i dettagli (mascherati). Puoi cercare per percorso, strumento o nome della chiave, mostrare solo gli errori (HTTP 400 e superiori) o solo le chiamate in attesa di conferma (428 e superiori) e limitare il periodo all'ultima ora, 24 ore o 7 giorni. NexCMP conserva le ultime 200,000 voci. Le modifiche effettuate tramite una chiave compaiono anche in Logs › Admin actions con il nome `ak:/`. ![Scheda Activity che elenca le chiamate con stato, client, tool e IP](https://nexcmp.com/it/docs/images/configure-with-ai/admin-api-keys-03-activity.webp) ## Verifica {#verify} Testa una chiave di sola lettura da qualsiasi macchina che si trovi all'interno dell'intervallo IP: ```bash curl -s https://cloud.example.com/v1/admin/agent/tools \ -H "Authorization: Bearer ak_XXXX" ``` Ottieni un elenco JSON dei tool consentiti dai tuoi ambiti. Esegui uno: ```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 '{}' ``` Il tempo **Last used** della chiave si aggiorna e la chiamata compare in **Activity**. L'elenco completo dei tool e una descrizione OpenAPI (`/v1/admin/openapi.json`) sono descritti in [Connect an AI client](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/). ## Errori {#errors} Gli errori sono in formato JSON: `{"error": {"code": "...", "message": "..."}}`. | HTTP | `code` | Significato | Soluzione | |---|---|---|---| | 401 | `invalid_key` | La chiave è mancante, non valida o sconosciuta. Viene restituito anche quando viene utilizzata una chiave `ak_` su un percorso non amministrativo. | Controlla la chiave; usala solo su `/v1/admin/` e `/mcp/admin`. | | 401 | `key_expired` | La scadenza della chiave è superata. | Crea una nuova chiave. | | 401 | `key_revoked` | La chiave è stata revocata. | Crea una nuova chiave. | | 403 | `ip_not_allowed` | L'IP del chiamante si trova al di fuori degli intervalli IP della chiave. | Effettua la chiamata da un IP consentito o crea una chiave con l'intervallo corretto. | | 403 | `local_only_key` | Una chiave creata per AI Chat o la CLI del server è stata utilizzata da un'altra macchina. | Queste chiavi funzionano solo sul server del pannello. | | 403 | `insufficient_scope` | La chiave non ha un ambito; la risposta include `required_scope`. | Crea una chiave con quell'ambito. | | 403 | `forbidden_for_keys` | L'endpoint, o l'impostazione che hai provato a modificare, è chiuso alle chiavi. | Esegui l'azione nell'area di amministrazione. | | 403 | `demo_read_only` | Il pannello è in modalità demo e la chiamata esegue una scrittura. | Usa un pannello non in modalità demo. | | 403 | `confirm_in_ui` | Questa azione deve essere confermata a schermo nell'interfaccia di amministrazione. | Approva la scheda di conferma. | | 428 | `confirm_required` | Un'anteprima è pronta; nulla è stato modificato. Include `confirm_token`. | Mostra l'anteprima, quindi ripeti con `X-Confirm-Token`. | | 409 | `confirm_expired` | Il token risale a più di 5 minuti fa. | Invia nuovamente la richiesta per ottenere una nuova anteprima. | | 409 | `confirm_mismatch` | Il token appartiene a una richiesta diversa (metodo, percorso o corpo differenti). | Ripeti la richiesta identica. | | 409 | `confirm_invalid` | Token sconosciuto o già utilizzato. | Invia nuovamente la richiesta per ottenere una nuova anteprima. | | 429 | `rate_limited` | Troppe chiamate in questo minuto. | Attendi `Retry-After`. | | 400 | `invalid_path` | Il percorso contiene sequenze non consentite. | Usa un percorso semplice. | | 413 | `too_large` | Il corpo supera i 10 MB. | Invia meno dati. | | 400 | `invalid_argument` | Un argomento del tool è mancante, sconosciuto o ha il tipo errato; il messaggio lo specifica. | Correggi l'argomento. | ## Limiti e note {#limits-notes} - Mantieni le chiavi di breve durata e con permessi limitati. Preferisci una chiave per client in modo da poter revocarne una singola. - Una chiave è potente quanto i suoi ambiti. `secrets:write` unito a `billing:write` è la combinazione più sensibile; le azioni finanziarie si fermano comunque a un'anteprima. - Le chiavi create automaticamente (per AI Chat, la CLI del server) durano solo pochi minuti e funzionano esclusivamente dal server del pannello. - Per disattivare immediatamente un client AI, revoca la sua chiave. Le connessioni OAuth vengono revocate nella scheda **Connected apps** ([OAuth connectors](https://nexcmp.com/it/docs/configure-with-ai/oauth-connectors/)).