Crea un token API e fai la prima chiamata

Crea un token con lo scope più piccolo che funziona

I token vengono creati nel pannello sotto l'account e portano gli scope: read, write, billing. Un token con write può ordinare server, il che significa che uno trapelato costa denaro. Dai a uno script di monitoraggio read e niente di più.

Due impostazioni utili da usare mentre sei lì: una data di scadenza e una restrizione di origine che fissa il token al prefisso da cui parte la tua automazione. Entrambe sono opzionali. Entrambe sono a basso costo.

Il valore viene mostrato una volta sola, perché memorizziamo un hash di esso piuttosto che il token. Perderlo significa crearne un altro.

export Paragon_TOKEN=...

Meglio della cronologia di shell, su una macchina che gira senza supervisione:

systemd-creds encrypt token.txt /etc/credstore.encrypted/paragon-token

La prima chiamata

curl -s https://paragonvps.com/api/v1/account -H "Authorization: Bearer $Paragon_TOKEN" | jq .

Tutto è JSON, tutto vive sotto /api/v1, e ogni risposta porta un header request_id. Cita quello in un ticket e troviamo la chiamata esatta in secondi invece di chiederti che ora era.

curl -s https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" | jq -r '.[] | .id + " " + .hostname + " " + .site + " " + .state'

Ordinarne uno

curl -s -X POST https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: 2026-07-16-edge-01" -d '{"plan":"r-8","site":"AMS-01","image":"debian-13","hostname":"edge-01","ssh_keys":["primary"]}'

Invia l'header Idempotency-Key. Ripetere una POST senza uno è come si finisce con due server e una sola intenzione; la chiave viene ricordata per ventiquattro ore e restituisce il risultato originale piuttosto che costruire una seconda istanza. I dati user-data di cloud-init vanno nello stesso corpo, codificati in base64, sotto user_data_b64.

Un ordine attinge al saldo del tuo account quando il saldo copre il primo ciclo. Altrimenti la risposta porta una fattura e un indirizzo di pagamento, e l'istanza appare una volta che la fattura viene saldata.

Limiti di frequenza ed errori

Seicento richieste al minuto per token. Se lo superi, ottieni un 429 con un header Retry-After, che è lì per essere letto piuttosto che sostituito con un sleep fisso in un loop.

Gli errori sono JSON che portano un code, un message umano e il request_id. Lo status ti dà la classe: 400 hai inviato qualcosa di sbagliato, 401 il token è invalido o revocato, 403 al token manca lo scope, 404 non esiste o non è tuo, 409 l'istanza è in uno stato che non può fare quello, e 5xx è nostro.

Paginazione e polling

Le collezioni prendono ?page= e ?per_page= e restituiscono un header Link. Le operazioni lunghe ti danno un job piuttosto che bloccare, il che copre provisioning, migrazione e ripristino:

curl -s https://paragonvps.com/api/v1/jobs/<job-id> -H "Authorization: Bearer $Paragon_TOKEN" | jq -r .state

Polling ogni pochi secondi, o registra un webhook e smetti del tutto di fare polling. I webhook sono firmati; controlla la firma prima di agire su uno.

Revoca

Istantanea, dal pannello o con un altro token:

curl -s -X DELETE https://paragonvps.com/api/v1/tokens/<token-id> -H "Authorization: Bearer $Paragon_TOKEN"

Le richieste in volo finiscono e la prossima ottiene un 401. Se sospetti che un token sia trapelato, revoca prima e indaga dopo. Un token non può cambiare l'email del tuo account o il tuo secondo fattore, ma può certamente spendere denaro.

Il riferimento completo, ogni endpoint e ogni campo, è su /docs/api.