Ein API-Token erstellen und den ersten Aufruf ausführen

Erstellen Sie ein Token mit dem kleinstmöglichen Umfang, der funktioniert

Tokens werden im Panel unter dem Konto erstellt und tragen Berechtigungen: read, write, billing. Ein Token mit write kann Server bestellen, was bedeutet, dass ein geleaktes Token Geld kostet. Geben Sie einem Monitoring-Skript read und nicht mehr.

Zwei Einstellungen, die sich lohnen, während Sie dort sind: ein Ablaufdatum und eine Quellenbeschränkung, die das Token auf das Präfix festlegt, von dem Ihre Automatisierung ausgeführt wird. Beide sind optional. Beide sind billig.

Der Wert wird nur einmal angezeigt, da wir einen Hash davon speichern und nicht das Token. Wenn Sie es verlieren, müssen Sie ein neues erstellen.

export Paragon_TOKEN=...

Besser als die Shell-Historie, auf einem Rechner, der unbeaufsichtigt läuft:

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

Der erste Aufruf

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

Alles ist JSON, alles befindet sich unter /api/v1, und jede Antwort enthält einen request_id-Header. Zitieren Sie das in einem Ticket und wir finden den genauen Aufruf in Sekunden, anstatt Sie zu fragen, wie spät es war.

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

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

Senden Sie den Idempotency-Key-Header. Einen POST ohne diesen zu wiederholen ist der Weg, auf dem Leute am Ende zwei Server und eine Absicht haben; der Schlüssel wird für vierundzwanzig Stunden gespeichert und gibt das ursprüngliche Ergebnis zurück, anstatt eine zweite Instanz zu erstellen. Cloud-init-Benutzerdaten gehen im selben Body, base64-kodiert, unter user_data_b64.

Eine Bestellung greift auf Ihr Kontoguthaben zurück, wenn das Guthaben den ersten Zyklus abdeckt. Andernfalls enthält die Antwort eine Rechnung und eine Zahlungsadresse, und die Instanz erscheint, sobald die Rechnung beglichen ist.

Ratenlimits und Fehler

Sechshundert Anfragen pro Minute pro Token. Wenn Sie das überschreiten, erhalten Sie einen 429 mit einem Retry-After-Header, der dazu da ist, gelesen zu werden, anstatt durch eine feste Schlafschleife ersetzt zu werden.

Fehler sind JSON mit einem code, einem menschenlesbaren message und dem request_id. Der Status gibt die Klasse an: 400 Sie haben etwas Falsches gesendet, 401 das Token ist ungültig oder widerrufen, 403 das Token hat nicht den erforderlichen Umfang, 404 es existiert nicht oder gehört nicht Ihnen, 409 die Instanz ist in einem Zustand, der das nicht zulässt, und 5xx ist unseres.

Paginierung und Polling

Sammlungen nehmen ?page= und ?per_page= und geben einen Link-Header zurück. Lange Operationen übergeben Ihnen einen Job, anstatt zu blockieren, was Provisionierung, Migration und Wiederherstellung abdeckt:

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

Pollen Sie das alle paar Sekunden oder registrieren Sie einen Webhook und hören Sie ganz auf zu pollen. Webhooks sind signiert; überprüfen Sie die Signatur, bevor Sie darauf reagieren.

Widerrufen

Sofort, vom Panel oder mit einem anderen Token:

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

Laufende Anfragen werden abgeschlossen und die nächste erhält einen 401. Wenn Sie vermuten, dass ein Token geleakt wurde, widerrufen Sie zuerst und untersuchen Sie danach. Ein Token kann nicht Ihre Kontomail oder Ihren zweiten Faktor ändern, aber es kann definitiv Geld ausgeben.

Die vollständige Referenz, jeder Endpoint und jedes Feld, finden Sie unter /docs/api.