Maak een API-token en doe de eerste aanroep

Maak een token met de kleinst mogelijke scope die werkt

Tokens worden aangemaakt in het paneel onder het account en hebben scopes: read, write, billing. Een token met write kan servers bestellen, wat betekent dat een gelekt token geld kost. Geef een monitoringsscript read en niets meer.

Twee instellingen die het overwegen waard zijn terwijl je daar bent: een vervaldatum en een bronbeperking die het token vastpint aan het prefix waar je automatisering draait. Beide zijn optioneel. Beide zijn goedkoop.

De waarde wordt één keer getoond, omdat we er een hash van opslaan in plaats van het token. Verlies je het, dan moet je een nieuwe maken.

export Paragon_TOKEN=...

Beter dan shell-geschiedenis, op een machine die onbeheerd draait:

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

De eerste aanroep

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

Alles is JSON, alles staat onder /api/v1 en elk antwoord bevat een request_id-header. Vermeld dat in een ticket en we vinden de exacte aanroep binnen enkele seconden in plaats van je te vragen hoe laat het was.

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

Een server bestellen

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

Stuur de Idempotency-Key-header. Een POST zonder deze header opnieuw proberen is hoe mensen eindigen met twee servers en één intentie; de sleutel wordt vierentwintig uur onthouden en retourneert het oorspronkelijke resultaat in plaats van een tweede instance te bouwen. Cloud-init user-data gaat in dezelfde body, base64-gecodeerd, onder user_data_b64.

Een bestelling doet een beroep op je accountsaldo als het saldo de eerste cyclus dekt. Anders bevat het antwoord een factuur en een betaaladres, en verschijnt de instance zodra de factuur is voldaan.

Limieten en fouten

Zeshonderd verzoeken per minuut per token. Overschrijd je dit, dan krijg je een 429 met een Retry-After-header, die er is om te worden gelezen in plaats van te worden vervangen door een vaste sleep in een lus.

Fouten zijn JSON met een code, een leesbare message en de request_id. De status geeft je de klasse: 400 je hebt iets verkeerd verzonden, 401 het token is ongeldig of ingetrokken, 403 het token mist de scope, 404 het bestaat niet of is niet van jou, 409 de instance is in een staat die dat niet toestaat, en 5xx is onze fout.

Paginering en polling

Collecties nemen ?page= en ?per_page= en retourneren een Link-header. Lange bewerkingen leveren een taak op in plaats van te blokkeren, wat provisioning, migratie en herstel omvat:

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

Poll dat elke paar seconden, of registreer een webhook en stop helemaal met pollten. Webhooks zijn ondertekend; controleer de handtekening voordat je er een verwerkt.

Intrekken

Onmiddellijk, via het paneel of met een ander token:

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

In-flight verzoeken worden afgerond en het volgende krijgt een 401. Als je vermoedt dat een token is gelekt, trek het dan eerst in en onderzoek daarna. Een token kan je account-e-mail of je tweede factor niet wijzigen, maar het kan zeker geld uitgeven.

De volledige referentie, elk endpoint en elk veld, staat op /docs/api.