Admin API keys

Di mana letaknya di admin: System › Settings › API & AI agents (/agent/keys), tab API keys. Halaman yang sama memiliki tab Connect an AI, Connected apps, dan Activity.

Fungsi

Admin API key (awalan ak_) memungkinkan klien AI atau skrip mengelola panel Anda dengan izin yang persis Anda berikan. Kunci ini berfungsi pada admin API di bawah /v1/admin/ dan pada endpoint admin MCP /mcp/admin. Kunci ini tidak berfungsi di tempat lain.

Tidak sama dengan kunci pelanggan

Pelanggan membuat kunci yang dimulai dengan vk_ di portal pelanggan (API keys and scopes). Kunci tersebut hanya menjangkau customer API dan /mcp. Kunci ak_ ditolak pada customer API, dan kunci vk_ ditolak pada admin API.

Persyaratan

Item	Persyaratan
Role	Anda harus masuk sebagai admin. Kunci tidak dapat membuat kunci lain.
Demo	Pada panel demo, halaman ini bersifat baca-saja (read-only): tidak ada kunci yang dapat dibuat atau dicabut.
Keterjangkauan	Klien harus dapat mencapai https://cloud.example.com/mcp/admin atau /v1/admin/... pada panel Anda (periksa firewall Anda jika menggunakan pembatasan IP).

Create a key

1. Buka System › Settings › API & AI agents dan tetap berada di tab API keys.

2. Klik Create new key.

3. Isi formulir berikut:

   Kolom	Aturan
   Name	Hingga 60 karakter, misalnya "Claude Code on my laptop".
   Cakupan	Centang setidaknya satu. Lihat Scopes. Mulai dengan admin:read saja.
   Expiry	1, 7, 30, 60, atau 90 hari. Default 30. Maksimum 90. Kunci tanpa masa kedaluwarsa tidak dapat dibuat.
   IP ranges (optional)	Satu alamat IPv4/IPv6 atau CIDR per baris, misalnya 203.0.113.0/24 atau 2001:db8::/48. Maksimal 32. Kosongkan untuk mengizinkan semua IP.
   Calls per minute	1 hingga 6000. Default 120.

4. Klik Create key. Sebuah kotak akan menampilkan kunci satu kali, misalnya ak_XXXX. Salin sekarang: NexCMP hanya menyimpan hash dan tidak akan pernah menampilkannya lagi.

5. Klik I have saved the key. Buka tab Connect an AI untuk mendapatkan perintah siap tempel yang sudah berisi kunci yang baru saja Anda buat (hanya di halaman ini, hingga Anda memuat ulang).

Cakupan

Kunci hanya dapat menggunakan alat dan titik akhir yang diizinkan oleh cakupannya. Cakupan tulis tidak menyertakan akses baca: kunci yang perlu membaca dan menulis juga memerlukan admin:read.

Cakupan	Apa yang diizinkannya
admin:read	Membaca pengaturan, katalog, pelanggan, penagihan, dan log. Rahasia tidak pernah dikembalikan.
catalog:write	Paket, templat OS, kuota, kode diskon.
infra:write	Sumber infrastruktur (CloudStack, Proxmox), zona, server.
billing:write	Gateway pembayaran, mata uang, faktur, saldo. Tindakan keuangan memerlukan konfirmasi.
customers:write	Pelanggan dan reseller.
settings:write	Pengaturan umum, branding, email, halaman legal, modul, notifikasi.
ai:write	Penyedia AI dan fitur AI.
secrets:write	Menulis kata sandi dan API keys. Dapat diatur tetapi tidak pernah dapat dibaca kembali.

Menetapkan rahasia memerlukan dua cakupan

Setiap panggilan yang membawa kata sandi, API key, atau nilai token (kata sandi SMTP, kunci pembayaran, token bot Telegram, kunci penyedia AI, kredensial CloudStack atau Proxmox) memerlukan secrets:write dan cakupan area tersebut (misalnya settings:write untuk SMTP). Jika Anda lebih suka mengetik rahasia sendiri, biarkan secrets:write nonaktif dan masukkan di admin.

Mencabut key

1. Temukan key dalam tabel (status Active, Expired, atau Revoked; Last used menunjukkan waktu dan klien).
2. Klik Revoke lalu konfirmasikan.

Key langsung berhenti berfungsi. Pencabutan bersifat permanen; buat key baru jika Anda membutuhkannya lagi.

Hal yang tidak boleh dilakukan oleh kunci

Key tidak akan pernah dapat mencapai area ini, apa pun cakupannya. Area tersebut memerlukan Anda masuk ke admin.

• Membuat atau mengubah pengguna administrator, 2FA dan keamanan masuk, sesi admin, dan token admin API.
• Membuat, mencantumkan, atau mencabut kunci admin, koneksi OAuth, dan akun AI, atau menggunakan AI Console.
• Membuat cadangan atau memulihkan panel, memperbaruinya, atau mengubah lisensinya.
• Masuk sebagai pelanggan atau reseller, membuka konsol pelanggan, membaca kredensial VM atau kubeconfig, mengatur SSH keys, atau mengirim atau menyetel ulang kata sandi.
• Mengubah modul jaringan dan perutean (BGP, FRR, RTBH, XDP, antarmuka, rute statis dan kebijakan, NAT) atau agen eksternal dan integrasi portal. Ini bersifat baca-saja.
• Mengubah pengaturan seperti demo_*, admin_*, daftar host, passkey, autentikasi ulang, dan rahasia captcha.

Apa pun yang tidak tercakup oleh aturan secara default ditutup untuk penulisan, dan dapat dibaca dengan admin:read untuk pembacaan.

Tindakan yang memerlukan konfirmasi Anda

Ini berhasil hanya setelah Anda menyetujui pratinjau (lihat Two-step confirmation):

• Mengubah saldo pelanggan atau dompet reseller, mencairkan dana, catatan penagihan, nilai tukar.
• Mengubah harga (harga paket, pembuatan paket massal, penetapan harga gambar dan penyimpanan) serta membuat kode diskon atau uang.
• Menyimpan kredensial gateway pembayaran atau koneksi CloudStack.
• Menghapus apa pun, memblokir atau menghapus pelanggan, mengubah batas pelanggan, menangguhkan atau menutup reseller.
• Bertindak pada server pelanggan, atau membuat server berbayar untuk pelanggan.
• Mengubah sakelar seluruh situs, pengaturan keamanan masuk, atau pengaturan pembayaran melalui pengaturan umum.

Konfirmasi dua langkah

Ketika sebuah panggilan memerlukan konfirmasi, belum ada yang berubah. Jawabannya adalah HTTP 428 dengan confirm_required, confirm_token, preview (metode, jalur, alasan, nilai baru, dan jika tersedia, nilai saat ini) dan expires_in: 300.

1. Klien menampilkan pratinjau kepada Anda.
2. Setelah Anda menyetujui, klien mengulangi permintaan yang sama (metode, jalur, dan isi yang sama) dengan header X-Confirm-Token: <confirm_token>. Alat MCP menggunakan argumen confirm_token sebagai gantinya.
3. Token berfungsi sekali dan kedaluwarsa setelah 5 menit.

Key yang dibuat di dalam admin untuk AI Chat hanya dapat dikonfirmasi di layar: jawabannya menyatakan confirm_in: "ui" dan kartu konfirmasi muncul di admin. AI tidak dapat menyetujuinya.

Aturan batas kecepatan dan IP

• Melewati batas per menit, panggilan akan mengembalikan rate_limited (HTTP 429) dengan Retry-After: 60.
• Jika rentang IP diatur, panggilan dari alamat lain akan mengembalikan ip_not_allowed (HTTP 403).

Log aktivitas

Tab Activity mencatat setiap panggilan yang dibuat menggunakan kunci, diurutkan dari yang terbaru: waktu, kunci, klien, jalur kedatangan (http, mcp, chat, cli, confirm, preview), metode dan jalur, alat, status HTTP, IP, serta detail (yang disamarkan). Anda dapat mencari berdasarkan jalur, alat, atau nama kunci, hanya menampilkan kesalahan (HTTP 400 ke atas) atau panggilan yang menunggu konfirmasi (428 ke atas), serta membatasi periode ke satu jam terakhir, 24 jam, atau 7 hari. NexCMP menyimpan 200,000 entri terbaru. Perubahan yang dilakukan melalui kunci juga muncul di Logs › Admin actions di bawah nama ak:<admin>/<key name>.

Verifikasi

Uji kunci baca-saja dari mesin mana pun yang berada di dalam rentang IP:

curl -s https://cloud.example.com/v1/admin/agent/tools \
  -H "Authorization: Bearer ak_XXXX"

Anda akan mendapatkan daftar JSON dari alat yang diizinkan oleh cakupan Anda. Jalankan salah satu:

curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \
  -H "Authorization: Bearer ak_XXXX" \
  -H "Content-Type: application/json" -d '{}'

Waktu Last used pada kunci akan berubah dan panggilan tersebut muncul di Activity. Daftar alat lengkap dan deskripsi OpenAPI (/v1/admin/openapi.json) dijelaskan di Connect an AI client.

Galat

Kesalahan berupa JSON: {"error": {"code": "...", "message": "..."}}.

HTTP	code	Arti	Solusi
401	invalid_key	Kunci tidak ada, salah format, atau tidak dikenal. Juga dikembalikan saat kunci ak_ digunakan pada jalur non-admin.	Periksa kunci; gunakan hanya pada /v1/admin/ dan /mcp/admin.
401	key_expired	Masa berlaku kunci telah kedaluwarsa.	Buat kunci baru.
401	key_revoked	Kunci telah dicabut.	Buat kunci baru.
403	ip_not_allowed	IP pemanggil berada di luar rentang IP kunci.	Lakukan panggilan dari IP yang diizinkan, atau buat kunci dengan rentang yang benar.
403	local_only_key	Kunci yang dibuat untuk AI Chat atau CLI server digunakan dari mesin lain.	Kunci ini hanya berfungsi pada server panel itu sendiri.
403	insufficient_scope	Kunci tidak memiliki cakupan; jawaban menyertakan required_scope.	Buat kunci dengan cakupan tersebut.
403	forbidden_for_keys	Titik akhir, atau pengaturan yang coba Anda ubah, ditutup untuk kunci.	Lakukan di admin.
403	demo_read_only	Panel berada dalam mode demo dan panggilan melakukan penulisan.	Gunakan panel non-demo.
403	confirm_in_ui	Tindakan ini harus dikonfirmasi di layar dalam admin.	Setujui kartu konfirmasi.
428	confirm_required	Pratinjau sudah siap; tidak ada yang berubah. Menyertakan confirm_token.	Tampilkan pratinjau, lalu ulangi dengan X-Confirm-Token.
409	confirm_expired	Token lebih lama dari 5 menit.	Kirim permintaan lagi untuk pratinjau baru.
409	confirm_mismatch	Token milik permintaan yang berbeda (metode, jalur, atau isi berbeda).	Ulangi permintaan yang persis sama.
409	confirm_invalid	Token tidak dikenal atau sudah digunakan.	Kirim permintaan lagi untuk pratinjau baru.
429	rate_limited	Terlalu banyak panggilan pada menit ini.	Tunggu hingga Retry-After.
400	invalid_path	Jalur berisi urutan yang dilarang.	Gunakan jalur biasa.
413	too_large	Isi melebihi 10 MB.	Kirim data yang lebih sedikit.
400	invalid_argument	Argumen alat tidak ada, tidak dikenal, atau jenisnya salah; pesan menyebutkannya.	Perbaiki argumen tersebut.

Batas & catatan

• Buat kunci berumur pendek dan spesifik. Lebih baik gunakan satu kunci per klien agar Anda dapat mencabut satu kunci saja.
• Kunci memiliki kekuatan sebesar cakupannya. secrets:write ditambah billing:write adalah kombinasi paling sensitif; tindakan yang melibatkan uang tetap berhenti pada pratinjau.
• Kunci yang dibuat secara otomatis (untuk AI Chat, CLI server) hanya aktif selama beberapa menit dan hanya berfungsi dari server panel.
• Untuk memutuskan sambungan klien AI seketika, cabut kuncinya. Koneksi OAuth dicabut pada tab Connected apps (OAuth connectors).