Kunci API dan cakupan

Di mana di portal: API keys (/api-keys). Di mana di admin: Customers › Customers › API keys (/customers/apikeys).

Fungsi

Sebuah API key memungkinkan skrip, pekerjaan CI, cmp CLI, atau asisten AI (MCP) memanggil REST API atas nama pelanggan, hanya dengan izin (cakupan) yang diberikan. Kunci pelanggan dimulai dengan vk_. Mereka dapat membaca dan mengelola layanan tetapi tidak pernah dapat menyentuh keuangan atau akun itu sendiri.

Persyaratan

Item	Persyaratan
Pelanggan	Sesi portal yang sedang masuk (kunci tidak dapat membuat atau mengedit kunci lain, dan administrator yang menyamar sebagai pelanggan juga tidak dapat melakukannya).
Switch	Kunci API diaktifkan secara default. Jika dimatikan, panggilan akan merespons 401 api_keys_disabled.
Dependensi	Cakupan produk hanya akan muncul jika produk tersebut diaktifkan di situs.

Membuat kunci (pelanggan)

1. Masuk ke portal dan buka API keys.

2. Klik Create key.

3. Isi formulir berikut:

   Kolom	Aturan
   Key name	Wajib diisi, hingga 60 karakter ("deploy server", "backup script").
   Apa yang dapat dilakukan kunci ini	Centang cakupan yang Anda perlukan — minimal satu. Kunci baca-saja sebaiknya tidak memiliki cakupan tulis. Harap berhati-hati dengan cakupan yang memerlukan biaya atau menghapus data.
   Expiry	Tidak pernah, 30 hari, 90 hari, atau 1 tahun (API menerima 1 hingga 3650 hari).
   Hanya izinkan panggilan dari IP ini	Satu IP atau rentang CIDR per baris, hingga 20 (IPv4 atau IPv6). Kosong berarti IP apa pun. Sematkan IP server Anda jika memungkinkan.

4. Konfirmasikan formulir. Kunci hanya ditampilkan sekali dalam jendela "Key created — shown ONCE". Salin kunci tersebut dan klik I saved the key. Hanya hash SHA-256 yang disimpan, sehingga administrator pun tidak dapat membacanya kembali; jika Anda Kehilangan kunci tersebut, cabut dan buat yang baru.

5. Portal juga menampilkan perintah curl siap pakai untuk menguji kunci tersebut.

Kunci akan terlihat seperti vk_ diikuti oleh string acak yang panjang. Daftar hanya menampilkan karakter pertama (misalnya vk_a1b2c3d4), cakupan, masa berlaku, penggunaan terakhir, jumlah permintaan, dan status (Active, Expired, Revoked).

Edit, cabut, audit

• Edit mengubah nama, cakupan, IP yang diizinkan, dan masa kedaluwarsa. Tidak diizinkan selama sesi yang ditiru.
• Revoke segera menghentikan kunci dan tidak dapat dibatalkan. Baris tetap disimpan agar log penggunaannya tetap tersedia.
• Key usage log menampilkan perintah tulis dan setiap kesalahan dari 60 hari terakhir: waktu, permintaan, kunci, hasil, dan IP sumber.
• Sebuah akun secara default dapat memiliki paling banyak 10 active keys.
• Kunci yang dibuat melalui CLI atau login MCP akan muncul di bawah Connected apps & devices dan dapat dicabut di sana.

Cakupan

Nama cakupan memiliki bentuk area:action. Cakupan mana yang ditawarkan bergantung pada produk yang Anda aktifkan.

Cakupan	Mengizinkan
catalog:read	Membaca paket dan katalog.
vm:read	Membaca VM, metrik, dan invoice VM.
vm:write	Tindakan daya, perubahan kecil, firewall, snapshot cepat.
vm:create	Membuat VM (berbayar).
vm:plan	Mengubah paket atau mengubah ukuran (berbayar).
vm:destroy	Menghapus VM.
vm:restore	Memulihkan VM dari snapshot (menimpa disk).
vm:console	Membuka tiket konsol VNC.
sshkey:read, sshkey:write	Membaca, menambahkan, dan menghapus SSH Keys.
volume:read, volume:write, volume:create, volume:destroy	Volume data (pembuatan dan penambahan ukuran berbayar; penghancuran menghilangkan data).
backup:read, backup:write, backup:restore	Backups (pemulihan menimpa disk).
billing:read	Dompet, invoice, riwayat pembayaran — hanya baca.
bandwidth:buy	Membeli add-on bandwidth (berbayar).
account:read, account:write	Profil, ringkasan, aktivitas, notifikasi; account:write hanya menandai notifikasi sebagai sudah dibaca.
apikey:read	Menampilkan kunci akun dan log penggunaan (tidak dapat membuat, mengedit, atau mencabut).
apikey:self	Implisit pada setiap kunci: memeriksa kunci yang memanggil (GET /v1/apikeys/self).
ticket:read, ticket:write	Tiket dukungan.
aff:read, transfer:read	Program afiliasi dan transfer layanan — hanya baca.
k8s:read, k8s:write, k8s:create, k8s:scale, k8s:destroy, k8s:kubeconfig	Kubernetes (pembuatan dan penskalaan berbayar; kubeconfig adalah cluster-admin).
vpc:read, vpc:write, vpc:create, vpc:destroy	Cloud Pribadi.
image:read, image:write	Image OS dan ISO (penyimpanan ditagih per jam).
s3:read, s3:write, s3:create, s3:destroy, s3:keys	Object Storage (rahasia S3 ditampilkan sekali).
vpn:read, vpn:detail, vpn:write, vpn:create, vpn:destroy	VPN dan proksi IPv6 (detail koneksi menyertakan kata sandi proksi).
dedicated:read, dedicated:write, dedicated:console, dedicated:create, dedicated:destroy	Dedicated servers (buat pesanan dari dompet; hancurkan instal ulang OS).
shield:read, shield:write, shield:agent	DDoS Shield, hanya jika modul tersebut diaktifkan.

Panggilan di luar cakupan kunci akan menjawab 403 scope_required; jalur yang tidak boleh dipanggil oleh kunci mana pun akan menjawab 403 endpoint_not_public.

Hal yang tidak boleh dilakukan oleh kunci

Tidak ada cakupan yang membuka: mengisi ulang atau menarik uang, mengubah kartu atau pengisian ulang otomatis, mengubah kata sandi, email atau 2FA, menghapus akun, membuat, mengedit, atau mencabut kunci lain. Tindakan ini selalu memerlukan peramban yang masuk. Bahkan kunci yang bocor tidak dapat menyentuh uang atau akun pelanggan.

Aturan yang dapat Andaandalkan

Aturan	Detail
Terikat situs	Kunci hanya berfungsi di situs (domain) tempat kunci tersebut dibuat.
Batas laju	Per kunci dan per akun: 120 dan 300 permintaan per menit secara default.
Idempotensi	Operasi yang memerlukan biaya atau tidak dapat diulang memerlukan header Idempotency-Key.
Quotas	Kunci tunduk pada quotas yang sama dengan pelanggan.
Akun terkunci	Kunci pelanggan yang dikunci berhenti berfungsi (403 account_blocked).
Audit	Pencabutan oleh administrator dicatat ke dalam log audit admin.

Tampilan administrator

1. Buka Customers › API keys (/customers/apikeys). Tabel menampilkan nama dan karakter pertama kunci, pemilik, cakupan, status, penggunaan terakhir (waktu, jumlah permintaan, IP), kedaluwarsa.
2. Filter berdasarkan situs jika Anda memiliki reseller. Cari berdasarkan nama, ID, atau awalan kunci.
3. Klik Revoke untuk menghentikan kunci aktif, atau Log untuk melihat penggunaannya.
4. Administrator melihat dan mencabut kunci tetapi tidak dapat membaca atau membuatkannya untuk pelanggan.

Verifikasi

1. Buat kunci dengan cakupan vm:read saja.
2. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" mengembalikan daftar VM.
3. curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX" merespons 403 scope_required.
4. Cabut kunci tersebut; panggilan pertama kini merespons 401 key_revoked.

Batas & catatan

• Kunci tidak akan pernah ditampilkan lagi. Perlakukan seperti kata sandi dan simpan di pengelola rahasia atau rahasia CI.
• Lebih baik gunakan satu kunci per skrip, cakupan minimal, masa kedaluwarsa singkat, dan daftar izin IP; lakukan rotasi dengan membuat kunci baru dan mencabut yang lama.
• Kunci dari login perangkat (CLI, MCP) secara default berlaku selama 90 hari.
• Sumber daya yang dihapus atau ditransfer tidak terdampak oleh pencabutan kunci.

Pemecahan Masalah

Gejala	Penyebab	Solusi
Error too_many_keys (422)	Batas kunci aktif (default 10) tercapai	Cabut kunci lama.
Error invalid_argument: tidak ada cakupan yang dipilih	Tidak ada cakupan yang dicentang	Centang setidaknya satu cakupan.
Error invalid_argument pada IP yang diizinkan	Entri bukan berupa IP atau rentang, panjang prefiks salah, atau lebih dari 20 entri	Satu IP atau CIDR per baris, contohnya 203.0.113.0/24.
Pembuatan ditolak selama peniruan identitas	impersonate_forbidden	Minta pelanggan untuk membuat kunci tersebut.
401 key_expired	Tanggal kedaluwarsa telah lewat	Buat kunci baru.
401 key_ip_denied	IP pemanggil tidak ada dalam daftar izin	Tambahkan IP atau kosongkan daftarnya.
401 api_keys_disabled	Fitur dimatikan	Tanyakan kepada administrator Anda (pengaturan api_keys_enabled).