Buat token API dan lakukan panggilan pertama

Buat token dengan lingkup terkecil yang berfungsi

Token dibuat di panel di bawah akun dan membawa lingkup: read, write, billing. Token dengan write dapat memesan server, yang berarti jika bocor akan memakan biaya. Berikan skrip pemantauan read dan tidak lebih.

Dua pengaturan yang layak digunakan saat Anda di sana: tanggal kedaluwarsa, dan pembatasan sumber yang mengikat token ke prefiks tempat otomatisasi Anda berjalan. Keduanya opsional. Keduanya murah.

Nilainya ditampilkan sekali, karena kami menyimpan hash darinya, bukan tokennya. Kehilangan berarti membuat yang baru.

export Paragon_TOKEN=...

Lebih baik daripada riwayat shell, di mesin yang berjalan tanpa pengawasan:

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

Panggilan pertama

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

Semuanya JSON, semuanya berada di bawah /api/v1, dan setiap respons membawa header request_id. Sebutkan itu dalam tiket dan kami menemukan panggilan yang tepat dalam hitungan detik, alih-alih bertanya jam berapa Anda melakukannya.

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

Memesan satu

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

Kirim header Idempotency-Key. Mengulang POST tanpa itu adalah cara orang berakhir dengan dua server dan satu niat; kunci tersebut diingat selama dua puluh empat jam dan mengembalikan hasil asli, bukan membuat instance kedua. Data user-data cloud-init masuk dalam body yang sama, di-encode base64, di bawah user_data_b64.

Pesanan menarik dari saldo akun Anda saat saldo menutupi siklus pertama. Jika tidak, respons membawa invoice dan alamat pembayaran, dan instance muncul setelah invoice diselesaikan.

Batas kecepatan dan kesalahan

Enam ratus permintaan per menit per token. Melewatinya dan Anda mendapat 429 dengan header Retry-After, yang ada untuk dibaca, bukan diganti dengan sleep tetap dalam loop.

Kesalahan adalah JSON yang membawa code, message yang dapat dibaca manusia, dan request_id. Status memberi Anda kelas: 400 Anda mengirim sesuatu yang salah, 401 token tidak valid atau dicabut, 403 token tidak memiliki lingkup, 404 tidak ada atau bukan milik Anda, 409 instance berada dalam keadaan yang tidak dapat melakukan itu, dan 5xx adalah milik kami.

Paginasi dan polling

Koleksi mengambil ?page= dan ?per_page= dan mengembalikan header Link. Operasi panjang memberi Anda pekerjaan daripada memblokir, yang mencakup provisioning, migrasi, dan restore:

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

Poll setiap beberapa detik, atau daftarkan webhook dan berhenti polling sama sekali. Webhook ditandatangani; periksa tanda tangan sebelum bertindak.

Mencabut

Instan, dari panel atau dengan token lain:

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

Permintaan yang sedang berjalan selesai dan yang berikutnya mendapat 401. Jika Anda curiga token bocor, cabut dulu dan selidiki setelahnya. Token tidak dapat mengubah email akun atau faktor kedua Anda, tetapi pasti dapat membelanjakan uang.

Referensi lengkap, setiap endpoint dan setiap bidang, ada di panel di bawah Token API.