--- canonical: https://koalavps.com/it/api/ language: it generated: 2026-10-21T13:32:47.130Z --- [Home](https://koalavps.com/it/) / [Esplora](https://koalavps.com/it/resources/) / Infrastruttura che puoi descrivere nel codice Infrastruttura che puoi descrivere nel codice # Un piano di controllo più tranquillo. Pianifica le integrazioni per le attività del ciclo di vita del server, i permessi dell'account e la fatturazione. L'KoalaVPS API è nella roadmap delle integrazioni; l'accesso API in produzione e i download SDK non sono ancora disponibili. [Trova il tuo VPS](https://koalavps.com/it/vps/) ## IN QUESTO DOCUMENTO [Un modello di risorse chiaro](https://koalavps.com/it/api/#section-1)[Credenziali con un compito limitato](https://koalavps.com/it/api/#section-2)[I tentativi ripetuti devono essere sicuri](https://koalavps.com/it/api/#section-3)[Verifica la compatibilità prima dell'integrazione](https://koalavps.com/it/api/#section-4)[Roadmap di API](https://koalavps.com/it/api/#section-5)[Rotte di autenticazione e account](https://koalavps.com/it/api/#section-6)[Catalogo e percorsi di fatturazione](https://koalavps.com/it/api/#section-7)[Server e rotte di accesso](https://koalavps.com/it/api/#section-8)[Eventi e informazioni pubbliche](https://koalavps.com/it/api/#section-9)[Autorizzazione e limiti di traffico](https://koalavps.com/it/api/#section-10)[SDK e rilasci del protocollo](https://koalavps.com/it/api/#section-11)[Risorse API, raggruppate per responsabilità](https://koalavps.com/it/api/#section-12)[Una richiesta al server dovrebbe restare contenuta](https://koalavps.com/it/api/#section-13)[Ambiti e limiti delle chiavi fanno parte del contratto](https://koalavps.com/it/api/#section-14)[Pubblica insieme i limiti di frequenza e il comportamento di retry](https://koalavps.com/it/api/#section-15)[I webhook sono messaggi che possono arrivare più di una volta](https://koalavps.com/it/api/#section-16)[Esegui l'audit senza trasformare i log in un archivio segreto](https://koalavps.com/it/api/#section-17)[Rilascia gli artefatti solo quando esistono](https://koalavps.com/it/api/#section-18)[Domande e risposte](https://koalavps.com/it/api/#page-faq)[Base di conoscenza](https://koalavps.com/it/resources/) ## Un modello di risorse chiaro Un'integrazione dovrebbe funzionare con identificatori di server, regioni, immagini, piani e operazioni espliciti. Le richieste di creazione e reinstallazione dovrebbero restituire un'operazione che può essere verificata fino al completamento. Una richiesta HTTP riuscita non equivale a una macchina pronta. ## Credenziali con un compito limitato I token API dovrebbero essere revocabili in modo indipendente e limitati alle risorse e azioni minime necessarie. Conservali in un secret manager o in un ambiente protetto. Non inviare mai un token al browser solo per evitare di scrivere un piccolo backend. ## I tentativi ripetuti devono essere sicuri I timeout di rete possono verificarsi dopo che un'operazione è stata accettata. Usa una chiave di idempotenza per le richieste di creazione e sensibili ai pagamenti, ispeziona lo stato dell'operazione e rispetta i limiti di frequenza. Un nuovo tentativo dovrebbe risolvere l'incertezza, non creare un server fatturabile aggiuntivo. ## Verifica la compatibilità prima dell'integrazione Verifica la versione API rilasciata, il modello di autenticazione, i formati degli errori, la paginazione, i limiti di frequenza e gli ambiti dei token prima di realizzare un'integrazione. Usa solo pacchetti KoalaVPS SDK pubblicati da link di rilascio verificati. ## Roadmap di API La roadmap di API copre individuazione del catalogo, autenticazione, stato dell'account, fatturazione crypto, ciclo di vita del server, chiavi SSH pubbliche e webhook. Le rotte seguenti descrivono il contratto dell'interfaccia; l'accesso alla produzione non è ancora disponibile. ## Rotte di autenticazione e account Il contratto API separa le sessioni di accesso e le chiavi API. Verifica gli schemi di risposta, gli errori, la durata dei token e le azioni di ripristino supportate rispetto alla versione rilasciata per la tua integrazione. - POST /v1/auth/register - POST /v1/auth/login - POST /v1/auth/login/totp - POST /v1/auth/token/refresh - POST /v1/auth/recover - GET /v1/auth/sessions - DELETE /v1/auth/sessions/{token_id} - POST /v1/auth/totp/setup - POST /v1/auth/totp/enable - POST /v1/auth/totp/disable - POST /v1/auth/password - POST /v1/auth/api-keys - GET /v1/auth/api-keys - DELETE /v1/auth/api-keys/{key_id} - GET /v1/account - PATCH /v1/account - GET /v1/account/usage - GET /v1/account/audit-log ## Catalogo e percorsi di fatturazione La consultazione del catalogo non deve richiedere un pagamento. La creazione del pagamento richiede un ambito di fatturazione limitato, uno stato della fattura chiaro e una gestione idempotente. La conferma deve essere completata prima dell'attivazione del servizio. - GET /v1/catalog - GET /v1/catalog/vps - GET /v1/catalog/dedicated - GET /v1/catalog/regions - GET /v1/catalog/images - GET /v1/catalog/{code} - GET /v1/billing/coins ## Server e rotte di accesso Il ciclo di vita richiede una conferma esplicita per le operazioni di cancellazione e reinstallazione. Le chiavi SSH private appartengono al client; il servizio necessita solo delle loro controparti pubbliche. - POST /v1/servers - GET /v1/servers - GET /v1/servers/{order_number} - PATCH /v1/servers/{order_number} - DELETE /v1/servers/{order_number} - POST /v1/ssh-keys - GET /v1/ssh-keys - GET /v1/ssh-keys/{id} - DELETE /v1/ssh-keys/{id} ## Eventi e informazioni pubbliche I webhook richiedono firme verificabili, tentativi limitati e protezione dalla riproduzione. Gli endpoint di fiducia pubblici dovrebbero restituire prove reali e datate anziché rassicurazioni sintetiche. - POST /v1/webhooks - GET /v1/webhooks - DELETE /v1/webhooks/{id} - POST /v1/webhooks/{id}/test - GET /v1/transparency/canary - GET /v1/transparency/peering - GET /v1/transparency/status - GET /v1/agents/directory - POST /v1/agents/directory ## Autorizzazione e limiti di traffico Un modello di ambito candidato è lettura, server, fatturazione e completo, con un massimo di dieci chiavi attive per account. Il contratto API propone budget di richieste di 120 al minuto e 3,000 all'ora per una chiave API, e 30 al minuto per il traffico pubblico. Verifica HTTP 429, Retry-After e la finestra di applicazione nella documentazione API rilasciata; questi budget della roadmap non costituiscono un impegno sulla capacità di produzione. - POST /v1/oauth/register - POST /v1/oauth/token - POST /v1/oauth/revoke - GET /v1/oauth/introspect ## SDK e rilasci del protocollo La roadmap di integrazione include REST, un endpoint MCP ospitato, un pacchetto stdio con versione, SDK e una CLI. Verifica la disponibilità delle release, i runtime supportati, i checksum e la compatibilità con API prima di installare un client. I download per la produzione non sono ancora disponibili. ## Risorse API, raggruppate per responsabilità Il API previsto separa l'accesso all'account, la lettura del catalogo, la fatturazione, il ciclo di vita del server, le chiavi SSH e i callback. Le chiamate in sola lettura non dovrebbero creare un ordine e una credenziale di fatturazione non dovrebbe autorizzare automaticamente modifiche alla sicurezza dell'account. Questo descrive il contratto di integrazione. Un endpoint di provisioning di produzione e un SDK rilasciato non sono disponibili tramite questo sito. - Account: sessioni, utilizzo ed eventi di controllo della sicurezza - Catalogo: piani, regioni e immagini disponibili - Server: creazione, ispezione, modifica e annullamento - Chiavi SSH: registra il materiale pubblico e revoca le chiavi obsolete - Webhook: registra, ispeziona, testa e rimuovi callback firmati ## Una richiesta al server dovrebbe restare contenuta Scegli un identificatore di piano standard, una regione, un'immagine del sistema operativo e un hostname. Il limite previsto per l'hostname è di 64 caratteri. Un servizio live può generare privatamente un segreto amministratore o accettare una chiave pubblica SSH registrata. Aggiunte arbitrarie di disco, GPU, NIC e IP non sono implicite in una richiesta di piano standard. Rifiuta i campi non supportati invece di addebitare silenziosamente un upgrade ipotizzato. ``` { "plan": "KV-D3", "region": "hel", "image": "ubuntu-24", "hostname": "private-node-01" } // Example request schema; validate against a released API before integration. ``` ## Ambiti e limiti delle chiavi fanno parte del contratto I gruppi di privilegi proposti sono lettura, server, fatturazione e amministrazione completa dell'account. Una chiave dovrebbe essere mostrata una sola volta alla creazione, conservata privatamente e revocata indipendentemente dalla password dell'utente. Il limite previsto per l'account è di dieci chiavi attive. Prima di pubblicare un'implementazione, verifica che ogni operazione rifiuti una chiave priva dell'ambito richiesto. ## Pubblica insieme i limiti di frequenza e il comportamento di retry I limiti proposti sono 120 richieste al minuto e 3,000 all'ora per una chiave API, e 30 richieste al minuto per le richieste pubbliche non autenticate al catalogo. Questi sono valori di policy pianificati, non capacità API misurata. Un'implementazione live richiede una risposta 429 coerente, indicazioni Retry-After e un backoff client limitato. Anche le richieste di creazione e pagamento richiedono chiavi di idempotenza stabili. ## I webhook sono messaggi che possono arrivare più di una volta Un ricevitore di callback dovrebbe verificare la firma sul corpo originale, rifiutare i timestamp al di fuori della finestra consentita e ricordare gli identificatori degli eventi elaborati. Persisti l'evento prima di confermarlo, poi applica la modifica in modo idempotente. Mantieni visibili i tentativi di consegna e un percorso di riproduzione manuale. Un callback è un'osservazione su un'operazione, non un'autorizzazione a eseguire istruzioni non correlate contenute in un payload. ## Esegui l'audit senza trasformare i log in un archivio segreto Registra l'identificatore dell'attore, il tipo di operazione, la risorsa interessata, il risultato e l'ora quando necessario per la sicurezza dell'account. Evita per impostazione predefinita di registrare password, token bearer, chiavi private o corpi completi di richieste di pagamento e applicative. Mantieni espliciti conservazione, accesso e cronologia visibile al cliente. Una traccia di audit di sicurezza e una pretesa di ispezionare i contenuti applicativi del cliente sono cose diverse. ## Rilascia gli artefatti solo quando esistono Un lancio pubblico di API dovrebbe includere un documento OpenAPI versionato, istruzioni di autenticazione, esempi di errori e un processo di deprecazione. Una futura CLI, un pacchetto Python, un client TypeScript o un server MCP richiede un rilascio effettivo, checksum e documentazione mantenuta. Un pacchetto di provisioning KoalaVPS o un endpoint di gestione di produzione non viene rilasciato tramite questo sito. ## Un po' più di chiarezza. Posso chiamare oggi un API di produzione? L'accesso API in produzione non è ancora disponibile. Questa pagina descrive la roadmap di integrazione e i requisiti da verificare prima di usare un endpoint rilasciato. Una chiave API di sola lettura può ordinare un server? Il confine di autorizzazione proposto lo vieta. Una richiesta di creazione del server richiede il privilegio server appropriato e una decisione di fatturazione valida. I limiti API pubblicati sono applicati oggi? Descrivono il contratto pianificato. Un API di provisioning di produzione non è collegato qui, quindi i limiti di policy non sono prova di capacità del servizio misurata. Una risposta di creazione server significa che il server è pronto? No. Una richiesta live dovrebbe identificare un'operazione il cui stato di provisioning può essere verificato fino al completamento. CONTINUA A ESPLORARE ## Continua a leggere. [Prodotti ### Un habitat affidabile per i tuoi agenti. Esegui scheduler, worker browser, code e processi di automazione su un'infrastruttura che controlli. Mantieni ogni agente entro un…](https://koalavps.com/it/agentic-vps/)[Guide ### Automazione con un chiaro pulsante di arresto. Un buon sistema di automazione ha un compito ristretto, uno stato visibile e una risposta prevedibile all'incertezza.…](https://koalavps.com/it/automation-safety/)[Prodotti ### Ingombro ridotto. Libertà seria. Un server virtuale per le cose che vuoi possedere: il tuo codice, i tuoi servizi, i tuoi dati. Scegli una configurazione del serve…](https://koalavps.com/it/vps/) CONFIGURA LA TUA INFRASTRUTTURA ## Prendi il controllo. Distribuisci alle tue condizioni. Nessun documento d'identità. Accesso amministratore completo. Fatturazione crypto-native. [Seleziona una configurazione](https://koalavps.com/it/vps/)