Control plane yang lebih tenang.

Model sumber daya yang jelas

Integrasi harus bekerja dengan pengenal server, region, image, paket, dan operasi yang eksplisit. Permintaan pembuatan dan pemasangan ulang harus mengembalikan operasi yang dapat diperiksa hingga selesai. Permintaan HTTP yang berhasil tidak sama dengan mesin yang siap.

Kredensial dengan tugas terbatas

Token API harus dapat dicabut secara independen dan dibatasi pada sumber daya serta tindakan minimum yang diperlukan. Simpan di pengelola rahasia atau lingkungan terlindungi. Jangan pernah mengirim token ke browser hanya untuk menghindari penulisan backend kecil.

Percobaan ulang harus aman

Timeout jaringan dapat terjadi setelah operasi diterima. Gunakan kunci idempotensi untuk permintaan pembuatan dan yang sensitif terhadap pembayaran, periksa status operasi, dan patuhi batas laju. Percobaan ulang harus menyelesaikan ketidakpastian, bukan membuat server tambahan yang dapat ditagih.

Periksa kompatibilitas sebelum integrasi

Periksa versi API yang dirilis, model autentikasi, format kesalahan, paginasi, batas laju, dan cakupan token sebelum membangun integrasi. Gunakan hanya paket KoalaVPS SDK yang diterbitkan dari tautan rilis terverifikasi.

Peta jalan API

Peta jalan API mencakup penemuan katalog, autentikasi, status akun, penagihan kripto, siklus hidup server, kunci SSH publik, dan webhook. Rute di bawah ini menjelaskan kontrak antarmuka; akses produksi belum tersedia.

Rute autentikasi dan akun

Kontrak API memisahkan sesi login dan kunci API. Periksa skema respons, kesalahan, masa berlaku token dan tindakan pemulihan yang didukung terhadap versi yang dirilis untuk integrasi Anda.

• POST /v1/auth/register
• POST /v1/auth/login
• POST /v1/auth/login/totp
• POST /v1/auth/token/refresh
• POST /v1/auth/recover
• GET /v1/auth/sessions
• DELETE /v1/auth/sessions/{token_id}
• POST /v1/auth/totp/setup
• POST /v1/auth/totp/enable
• POST /v1/auth/totp/disable
• POST /v1/auth/password
• POST /v1/auth/api-keys
• GET /v1/auth/api-keys
• DELETE /v1/auth/api-keys/{key_id}
• GET /v1/account
• PATCH /v1/account
• GET /v1/account/usage
• GET /v1/account/audit-log

Rute katalog dan penagihan

Pembacaan katalog tidak boleh memerlukan pembayaran. Pembuatan pembayaran membutuhkan cakupan penagihan yang terbatas, status faktur yang jelas, dan penanganan idempoten. Konfirmasi harus selesai sebelum aktivasi layanan.

• GET /v1/catalog
• GET /v1/catalog/vps
• GET /v1/catalog/dedicated
• GET /v1/catalog/regions
• GET /v1/catalog/images
• GET /v1/catalog/{code}
• GET /v1/billing/coins

Server dan rute akses

Siklus hidup memerlukan konfirmasi eksplisit untuk operasi pembatalan dan pemasangan ulang. Kunci SSH privat berada di klien; layanan hanya memerlukan pasangan publiknya.

• POST /v1/servers
• GET /v1/servers
• GET /v1/servers/{order_number}
• PATCH /v1/servers/{order_number}
• DELETE /v1/servers/{order_number}
• POST /v1/ssh-keys
• GET /v1/ssh-keys
• GET /v1/ssh-keys/{id}
• DELETE /v1/ssh-keys/{id}

Acara dan informasi publik

Webhook memerlukan tanda tangan yang dapat diverifikasi, percobaan ulang yang terbatas, dan perlindungan replay. Endpoint kepercayaan publik harus mengembalikan bukti bertanggal yang nyata, bukan jaminan sintetis.

• POST /v1/webhooks
• GET /v1/webhooks
• DELETE /v1/webhooks/{id}
• POST /v1/webhooks/{id}/test
• GET /v1/transparency/canary
• GET /v1/transparency/peering
• GET /v1/transparency/status
• GET /v1/agents/directory
• POST /v1/agents/directory

Otorisasi dan batas lalu lintas

Model cakupan kandidat adalah baca, server, penagihan, dan penuh, dengan maksimum sepuluh kunci aktif per akun. Kontrak API mengusulkan anggaran permintaan 120 per menit dan 3,000 per jam untuk kunci API, serta 30 per menit untuk lalu lintas publik. Periksa HTTP 429, Retry-After, dan jendela penegakan dalam dokumentasi API yang dirilis; anggaran peta jalan ini bukan komitmen kapasitas produksi.

• POST /v1/oauth/register
• POST /v1/oauth/token
• POST /v1/oauth/revoke
• GET /v1/oauth/introspect

SDK dan rilis protokol

Peta jalan integrasi mencakup REST, endpoint MCP terkelola, paket stdio berversi, SDKs, dan CLI. Periksa ketersediaan rilis, runtime yang didukung, checksum, dan kompatibilitas API sebelum memasang klien. Unduhan produksi belum tersedia.

Sumber daya API, dikelompokkan berdasarkan tanggung jawab

API yang dimaksudkan memisahkan akses akun, pembacaan katalog, penagihan, siklus hidup server, kunci SSH, dan callback. Panggilan hanya-baca tidak boleh membuat pesanan, dan kredensial penagihan tidak boleh secara otomatis mengotorisasi perubahan keamanan akun. Ini menjelaskan kontrak integrasi. Endpoint penyediaan produksi dan SDK yang dirilis tidak tersedia melalui situs ini.

• Akun: sesi, penggunaan, dan peristiwa audit keamanan
• Katalog: paket, wilayah, dan image yang tersedia
• Server: buat, periksa, ubah, dan batalkan
• Kunci SSH: daftarkan materi publik dan cabut kunci yang usang
• Webhook: daftarkan, periksa, uji, dan hapus callback bertanda tangan

Permintaan server harus tetap kecil

Pilih pengenal paket standar, wilayah, image OS, dan hostname. Batas hostname yang dimaksud adalah 64 karakter. Layanan aktif dapat membuat rahasia administrator secara privat atau menerima kunci publik SSH yang terdaftar. Penambahan disk, GPU, NIC, dan IP sewenang-wenang tidak tersirat oleh permintaan paket standar. Tolak bidang yang tidak didukung alih-alih menagih diam-diam untuk peningkatan yang ditebak.

{
  "plan": "KV-D3",
  "region": "hel",
  "image": "ubuntu-24",
  "hostname": "private-node-01"
}
// Example request schema; validate against a released API before integration.

Cakupan dan batas kunci adalah bagian dari kontrak

Grup hak istimewa yang diusulkan adalah baca, server, penagihan, dan administrasi akun penuh. Kunci harus ditampilkan sekali saat dibuat, disimpan secara privat, dan dicabut secara independen dari kata sandi pengguna. Batas akun yang dimaksud adalah sepuluh kunci aktif. Sebelum menerbitkan implementasi, verifikasi bahwa setiap operasi menolak kunci tanpa cakupan yang diperlukan.

Terbitkan batas laju dan perilaku percobaan ulang secara bersamaan

Batas yang diusulkan adalah 120 permintaan per menit dan 3,000 per jam untuk kunci API, serta 30 permintaan per menit untuk permintaan katalog publik tanpa autentikasi. Ini adalah nilai kebijakan yang direncanakan, bukan kapasitas API yang terukur. Implementasi langsung memerlukan respons 429 yang konsisten, panduan Retry-After, dan backoff klien yang terbatas. Permintaan pembuatan dan pembayaran juga memerlukan kunci idempotensi yang stabil.

Webhook adalah pesan yang dapat tiba lebih dari sekali

Penerima callback harus memverifikasi tanda tangan atas isi asli, menolak stempel waktu di luar jendela yang diizinkan, dan mengingat pengenal peristiwa yang telah diproses. Simpan peristiwa sebelum mengonfirmasinya, lalu terapkan perubahan secara idempoten. Tampilkan upaya pengiriman dan jalur pemutaran ulang manual. Callback adalah pengamatan atas suatu operasi, bukan izin untuk menjalankan instruksi tak terkait yang terkandung dalam payload.

Audit tanpa menjadikan log sebagai penyimpanan rahasia

Catat pengenal aktor, jenis operasi, sumber daya yang terdampak, hasil, dan waktu bila diperlukan untuk keamanan akun. Hindari mencatat kata sandi, token bearer, kunci privat, atau isi lengkap permintaan pembayaran dan aplikasi secara default. Jaga agar retensi, akses, dan riwayat yang terlihat pelanggan tetap eksplisit. Jejak audit keamanan dan klaim untuk memeriksa isi aplikasi pelanggan adalah dua hal yang berbeda.

Rilis artefak hanya saat sudah ada

Peluncuran API publik harus mencakup dokumen OpenAPI berversi, petunjuk autentikasi, contoh kesalahan, dan proses penghentian. CLI, paket Python, klien TypeScript, atau server MCP di masa depan memerlukan rilis aktual, checksum, dan dokumentasi yang dipelihara. Paket provisioning KoalaVPS atau endpoint manajemen produksi tidak dirilis melalui situs ini.

Sedikit lebih jelas.