Chiavi API amministrative

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

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.

Diverse dalle chiavi cliente

I clienti creano chiavi che iniziano con vk_ nel portale clienti (API keys and scopes). 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

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

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

Ambiti

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.

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

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

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

Queste vanno a buon fine solo dopo aver approvato un'anteprima (vedi 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

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

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

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:<admin>/<key name>.

Verifica

Testa una chiave di sola lettura da qualsiasi macchina che si trovi all'interno dell'intervallo IP:

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:

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.

Errori

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

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