Créer un jeton API et faire le premier appel

Créer un jeton avec le moins de droits possible

Les jetons sont créés dans le panneau, sous le compte, et portent des périmètres : read, write, billing. Un jeton avec write peut commander des serveurs, ce qui signifie qu'un jeton divulgué coûte de l'argent. Donnez à un script de supervision read et rien de plus.

Deux paramètres utiles pendant que vous y êtes : une date d'expiration et une restriction d'origine qui épingle le jeton au préfixe depuis lequel votre automatisation s'exécute. Les deux sont facultatifs. Les deux sont peu coûteux.

La valeur n'est affichée qu'une fois, car nous stockons un hachage de celle-ci plutôt que le jeton. Le perdre signifie en créer un autre.

export Paragon_TOKEN=...

Mieux que l'historique du shell, sur une machine qui fonctionne sans surveillance :

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

Le premier appel

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

Tout est en JSON, tout se trouve sous /api/v1, et chaque réponse comporte un en-tête request_id. Citez-le dans un ticket et nous trouvons l'appel exact en quelques secondes au lieu de vous demander à quelle heure il était.

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

En commander un

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"]}'

Envoyez l'en-tête Idempotency-Key. Renvoyer une requête POST sans celui-ci est la façon dont les gens se retrouvent avec deux serveurs et une seule intention ; la clé est mémorisée pendant vingt-quatre heures et renvoie le résultat d'origine plutôt que de construire une seconde instance. Les user-data cloud-init vont dans le même corps, encodées en base64, sous user_data_b64.

Une commande prélève sur le solde de votre compte lorsque le solde couvre le premier cycle. Sinon, la réponse comporte une facture et une adresse de paiement, et l'instance apparaît une fois la facture réglée.

Limites de débit et erreurs

Six cents requêtes par minute et par jeton. Au-delà, vous obtenez une 429 avec un en-tête Retry-After, qui est là pour être lu plutôt que remplacé par une attente fixe dans une boucle.

Les erreurs sont en JSON et comportent une code, un message humain et la request_id. Le statut vous donne la classe : 400 vous avez envoyé quelque chose d'incorrect, 401 le jeton est invalide ou révoqué, 403 le jeton n'a pas le périmètre requis, 404 cela n'existe pas ou ne vous appartient pas, 409 l'instance est dans un état qui ne permet pas cela, et 5xx est de notre côté.

Pagination et interrogation

Les collections acceptent ?page= et ?per_page= et renvoient un en-tête Link. Les opérations longues remettent une tâche plutôt que de bloquer, ce qui couvre l'approvisionnement, la migration et la restauration :

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

Interrogez cela toutes les quelques secondes, ou enregistrez un webhook et cessez d'interroger. Les webhooks sont signés ; vérifiez la signature avant d'agir sur l'un d'eux.

Révocation

Immédiate, depuis le panneau ou avec un autre jeton :

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

Les requêtes en cours se terminent et la suivante reçoit 401. Si vous soupçonnez qu'un jeton a fuité, révoquez d'abord et enquêtez ensuite. Un jeton ne peut pas modifier votre adresse e-mail ou votre second facteur, mais il peut certainement dépenser de l'argent.

La référence complète, chaque point de terminaison et chaque champ, est sur /docs/api.