Utwórz token API i wykonaj pierwsze wywołanie

Utwórz token z najmniejszym, działającym zakresem

Tokeny tworzy się w panelu na koncie i mają one zakresy: read, write, billing. Token z write może zamawiać serwery, co oznacza, że wyciek takiego tokena kosztuje pieniądze. Daj skryptowi monitorującemu read i nic więcej.

Dwa ustawienia, które warto włączyć przy okazji: data wygaśnięcia oraz ograniczenie źródła, które przypina token do prefiksu, z którego działa Twoja automatyzacja. Obie opcje są dobrowolne. Obie są tanie.

Wartość wyświetlana jest tylko raz, ponieważ przechowujemy jej skrót zamiast samego tokena. Jego utrata oznacza konieczność utworzenia kolejnego.

export Paragon_TOKEN=...

Lepiej niż historia powłoki na maszynie działającej bez nadzoru:

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

Pierwsze wywołanie

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

Wszystko jest JSON-em, wszystko znajduje się pod /api/v1, a każda odpowiedź zawiera nagłówek request_id. Cytuj go w zgłoszeniu, a znajdziemy dokładne wywołanie w kilka sekund zamiast pytać, o której godzinie to było.

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

Zamawianie serwera

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

Wyślij nagłówek Idempotency-Key. Ponawianie POST bez niego to sposób na dwa serwery i jeden zamiar; klucz jest pamiętany przez dwadzieścia cztery godziny i zwraca pierwotny wynik zamiast tworzyć drugą instancję. Dane cloud-init user-data umieszcza się w tym samym ciele, zakodowane base64, pod user_data_b64.

Zamówienie obciąża saldo konta, jeśli saldo pokrywa pierwszy okres rozliczeniowy. W przeciwnym razie odpowiedź zawiera fakturę i adres płatności, a instancja pojawia się po rozliczeniu faktury.

Limity zapytań i błędy

Sześćset zapytań na minutę na token. Przekroczenie tego limitu skutkuje odpowiedzią 429 z nagłówkiem Retry-After, który należy odczytać, a nie zastępować stałym opóźnieniem w pętli.

Błędy są JSON-em zawierającym code, czytelny dla ludzi message oraz request_id. Status określa klasę błędu: 400 oznacza, że wysłano coś niepoprawnego, 401 – token jest nieprawidłowy lub unieważniony, 403 – token nie ma wymaganego zakresu, 404 – zasób nie istnieje lub nie jest Twój, 409 – instancja jest w stanie, który nie pozwala na tę operację, a 5xx – błąd po naszej stronie.

Stronicowanie i odpytywanie

Kolekcje przyjmują ?page= i ?per_page= i zwracają nagłówek Link. Długotrwałe operacje zwracają zadanie zamiast blokować, co obejmuje provisioning, migrację i przywracanie:

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

Odpytywaj je co kilka sekund lub zarejestruj webhook i przestań odpytywać. Webhooki są podpisane; przed ich obsłużeniem zweryfikuj podpis.

Unieważnianie

Natychmiastowe, z panelu lub innym tokenem:

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

W locie zakończą się bieżące żądania, a następne otrzyma 401. Jeśli podejrzewasz wyciek tokena, najpierw go unieważnij, a potem badaj sprawę. Token nie może zmienić adresu e-mail konta ani drugiego składnika uwierzytelniania, ale może wydawać pieniądze.

Pełna dokumentacja, każdy punkt końcowy i każde pole, znajduje się pod adresem /docs/api.