Chiavi API e ambiti

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

Descrizione

Una API key consente a uno script, a un job CI, alla cmp CLI o a un assistente IA (MCP) di chiamare la REST 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

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)

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

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

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

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

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.

Verifica

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

• 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

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