---
title: Chiavi API e ambiti
description: Come i clienti creano chiavi API (prefisso vk_), scelgono gli scope, li limitano per IP e scadenza, e come gli amministratori le esaminano e le revocano.
url: https://nexcmp.com/it/docs/developers/api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Chiavi API e ambiti {#api-keys-and-scopes}

> **Dove nel portale:** API keys (`/api-keys`). **Dove nell'amministrazione:** Customers › Customers › API keys (`/customers/apikeys`).

## Descrizione {#what-it-does}

Una **API key** consente a uno script, a un job CI, alla [`cmp` CLI](https://nexcmp.com/it/docs/developers/cmp-cli/) o a un assistente IA ([MCP](https://nexcmp.com/it/docs/developers/mcp/)) di chiamare la [REST API](https://nexcmp.com/it/docs/developers/api/) per conto di un cliente, con i soli permessi (**scopes**) concessi. Le chiavi dei clienti iniziano con `vk_`. Possono leggere e gestire i servizi ma **non** possono mai toccare denaro o l'account stesso.

## Requisiti {#requirements}

| Elemento | Requisito |
|---|---|
| Cliente | Una sessione di portale attiva (una chiave non può creare o modificare altre chiavi, e un amministratore che impersona un cliente non può farlo). |
| Interruttore | Le chiavi API sono attive per impostazione predefinita. Se disattivate, le chiamate restituiscono 401 `api_keys_disabled`. |
| Dipendenze | Gli ambiti di un prodotto compaiono solo quando quel prodotto è abilitato sul sito. |

## Crea una chiave (cliente) {#create-a-key-customer}

1. Accedi al portale e apri **API keys**.
2. Fai clic su **Create key**.
3. Compila il modulo:

   | Campo | Regola |
   |---|---|
   | **Nome chiave** | Obbligatorio, fino a 60 caratteri ("deploy server", "backup script"). |
   | **Cosa può fare questa chiave** | Seleziona gli ambiti necessari — almeno uno. Una chiave di sola lettura non dovrebbe avere ambiti di scrittura. Fai attenzione agli ambiti che comportano costi o eliminazione di dati. |
   | **Expiry** | Mai, 30 giorni, 90 giorni o 1 anno (l'API accetta da 1 a 3650 giorni). |
   | **Consenti chiamate solo da questi IP** | Un IP o intervallo CIDR per riga, fino a 20 (IPv4 o IPv6). Vuoto significa qualsiasi IP. Associa l'IP del tuo server quando possibile. |

4. Conferma il modulo. La chiave viene mostrata **una sola volta** in una finestra "Key created — shown ONCE". Copiala e fai clic su **I saved the key**. Viene memorizzato solo un hash SHA-256, quindi nemmeno un amministratore può leggerla di nuovo; se la perdi, revocala e creane una nuova.
5. Il portale mostra anche un comando `curl` pronto per testare la chiave.


Una chiave appare come `vk_` seguita da una lunga stringa casuale. L'elenco mostra solo i primi caratteri (ad esempio `vk_a1b2c3d4`), gli ambiti, la scadenza, l'ultimo utilizzo, il conteggio delle richieste e lo stato (*Active*, *Expired*, *Revoked*).

### Modifica, revoca, audit {#edit-revoke-audit}

- **Edit** modifica il nome, gli ambiti, gli IP consentiti e la scadenza. Non è consentito durante una sessione impersonata.
- **Revoke** interrompe immediatamente la chiave e l'azione non può essere annullata. La riga viene conservata per mantenere disponibile il registro di utilizzo.
- **Key usage log** mostra i comandi di scrittura e ogni errore degli ultimi 60 giorni: ora, richiesta, chiave, risultato e IP di origine.
- Un account può contenere al massimo **10 chiavi attive** per impostazione predefinita.
- Le chiavi create tramite l'accesso CLI o MCP compaiono sotto **Connected apps & devices** e possono essere revocate lì.

## Ambiti {#scopes}

I nomi degli ambiti hanno la forma `area:action`. Quali vengono offerti dipende dai prodotti abilitati.

| Ambito | Consente |
|---|---|
| `catalog:read` | Leggere i piani e il catalogo. |
| `vm:read` | Leggere VM, metriche e fatture delle VM. |
| `vm:write` | Azioni di alimentazione, modifiche minori, firewall, snapshot rapidi. |
| `vm:create` | **Creare VM (comporta costi).** |
| `vm:plan` | **Cambiare piano o ridimensionare (comporta costi).** |
| `vm:destroy` | **Eliminare VM.** |
| `vm:restore` | **Ripristinare una VM da uno snapshot (sovrascrive il disco).** |
| `vm:console` | Aprire ticket per la console VNC. |
| `sshkey:read`, `sshkey:write` | Leggere, aggiungere e rimuovere chiavi SSH. |
| `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | Volumi di dati (creazione e ampliamento comportano costi, la distruzione comporta la perdita di dati). |
| `backup:read`, `backup:write`, `backup:restore` | Backups (il ripristino sovrascrive il disco). |
| `billing:read` | Portafoglio, fatture, cronologia dei pagamenti — **solo lettura**. |
| `bandwidth:buy` | **Acquistare un componente aggiuntivo di banda (comporta costi).** |
| `account:read`, `account:write` | Profilo, panoramica, attività, notifiche; `account:write` segna solo le notifiche come lette. |
| `apikey:read` | Elencare le chiavi dell'account e il registro di utilizzo (non è possibile creare, modificare o revocare). |
| `apikey:self` | Implicito su ogni chiave: ispezionare la chiave chiamante (`GET /v1/apikeys/self`). |
| `ticket:read`, `ticket:write` | Ticket di supporto. |
| `aff:read`, `transfer:read` | Programma di affiliazione e trasferimenti di servizi — solo lettura. |
| `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes (creazione e ridimensionamento comportano costi; kubeconfig è cluster-admin). |
| `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | Private Cloud. |
| `image:read`, `image:write` | Immagini OS e ISO (lo storage viene fatturato a ore). |
| `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage (il segreto S3 viene mostrato una sola volta). |
| `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPN e proxy IPv6 (i dettagli di connessione includono le password dei proxy). |
| `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | Server dedicati (creazione di ordini dal portafoglio; la distruzione reinstalla il sistema operativo). |
| `shield:read`, `shield:write`, `shield:agent` | DDoS Shield, solo quando quel modulo è abilitato. |

Una chiamata al di fuori degli ambiti della chiave risponde con **403 `scope_required`**; un percorso che nessuna chiave può chiamare risponde con **403 `endpoint_not_public`**.

### Cosa una chiave non può mai fare {#what-a-key-can-never-do}

Nessun ambito consente di: ricaricare o prelevare denaro, modificare carte o ricarica automatica, cambiare password, e-mail o 2FA, eliminare l'account, creare, modificare o revocare altre chiavi. Queste operazioni richiedono sempre un browser con sessione attiva. Nemmeno una chiave trafugata può accedere al denaro o all'account del cliente.

## Regole su cui fare affidamento {#rules-you-can-rely-on}

| Regola | Dettaglio |
|---|---|
| Vincolata al sito | Una chiave funziona solo sul sito (dominio) in cui è stata creata. |
| Limiti di velocità | Per chiave e per account: rispettivamente 120 e 300 richieste al minuto per impostazione predefinita. |
| Idempotency | Le operazioni che comportano costi o non possono essere ripetute richiedono un'intestazione `Idempotency-Key`. |
| Quote | Una chiave è soggetta alle stesse [quotas](https://nexcmp.com/it/docs/billing/quotas/) del cliente. |
| Account bloccato | Le chiavi di un cliente bloccato smettono di funzionare (403 `account_blocked`). |
| Audit | La revoca da parte di un amministratore viene registrata nel log di audit amministrativo. |

## Vista amministratore {#administrator-view}

1. Apri **Customers › API keys** (`/customers/apikeys`). La tabella mostra il nome della chiave e i primi caratteri, il proprietario, gli ambiti, lo stato, l'ultimo utilizzo (ora, conteggio richieste, IP) e la scadenza.
2. Filtra per sito se disponi di rivenditori. Cerca per nome, ID o inizio della chiave.
3. Fai clic su **Revoke** per interrompere una chiave attiva, oppure su **Log** per visualizzarne l'utilizzo.
4. Gli amministratori **visualizzano e revocano** le chiavi ma non possono leggerle o crearle per i clienti.

![Elenco amministrativo delle chiavi API dei clienti con ambiti, stato, ultimo utilizzo e pulsante Revoca](https://nexcmp.com/it/docs/images/developers/api-keys-02-admin.webp)

## Verifica {#verify}

1. Crea una chiave con il solo ambito `vm:read`.
2. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` restituisce l'elenco delle VM.
3. `curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX"` risponde con 403 `scope_required`.
4. Revoca la chiave; la prima chiamata ora risponde con 401 `key_revoked`.

## Limiti e note {#limits-notes}

- La chiave non viene più mostrata. Trattala come una password e memorizzala in un secret manager o nel secret di una CI.
- Preferisci una chiave per script, permessi minimi, una breve scadenza e un elenco di IP consentiti; esegui la rotazione creando una nuova chiave e revocando quella vecchia.
- Le chiavi per l'accesso da dispositivo (CLI, MCP) hanno una durata predefinita di 90 giorni.
- Risorse eliminate o trasferite non subiscono modifiche dalla revoca di una chiave.

## Troubleshooting {#troubleshooting}

| Sintomo | Causa | Soluzione |
|---|---|---|
| Errore `too_many_keys` (422) | Il limite di chiavi attive (10 per impostazione predefinita) è stato raggiunto | Revoca una chiave vecchia. |
| Errore `invalid_argument`: nessun permesso scelto | Nessun permesso spuntato | Seleziona almeno un permesso. |
| Errore `invalid_argument` sugli IP consentiti | Una voce non è un IP o un intervallo, la lunghezza del prefisso non è corretta o ci sono più di 20 voci | Un IP o CIDR per riga, ad esempio `203.0.113.0/24`. |
| La creazione viene rifiutata durante l'impersonificazione | `impersonate_forbidden` | Chiedi al cliente di creare la chiave. |
| 401 `key_expired` | Data di scadenza superata | Crea una nuova chiave. |
| 401 `key_ip_denied` | IP del chiamante non incluso nell'elenco degli IP consentiti | Aggiungi l'IP o svuota l'elenco. |
| 401 `api_keys_disabled` | Funzione disattivata | Rivolgiti al tuo amministratore (impostazione `api_keys_enabled`). |