---
title: Admin API keys
description: Buat dan cabut admin key ak_ untuk AI Agent dan skrip: delapan scope, masa berlaku, rentang IP, rate limit, batasan key, dan setiap kode error.
url: https://nexcmp.com/id/docs/configure-with-ai/admin-api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Admin API keys {#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 {#what-it-does}

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.

::: info Tidak sama dengan kunci pelanggan
Pelanggan membuat kunci yang dimulai dengan `vk_` di portal pelanggan ([API keys and scopes](https://nexcmp.com/id/docs/developers/api-keys/)). Kunci tersebut hanya menjangkau customer API dan `/mcp`. Kunci `ak_` ditolak pada customer API, dan kunci `vk_` ditolak pada admin API.
:::

## Persyaratan {#requirements}

| 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 {#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](#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).

![Dialog kunci baru dengan nama, kotak centang cakupan, masa kedaluwarsa, dan rentang IP terisi](https://nexcmp.com/id/docs/images/configure-with-ai/admin-api-keys-01-create.webp)

![Dialog yang menampilkan kunci baru satu kali beserta tombol Salin dan peringatan](https://nexcmp.com/id/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp)

## Cakupan {#scopes}

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. |

::: tip 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 {#revoke-a-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 {#what-a-key-can-never-do}

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 {#actions-that-need-your-confirmation}

Ini berhasil hanya setelah Anda menyetujui pratinjau (lihat [Two-step confirmation](#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 {#two-step-confirmation}

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 {#rate-limit-and-ip-rules}

- 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 {#activity-log}

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>`.

![Tab Activity yang mencantumkan panggilan dengan status, klien, alat, dan IP](https://nexcmp.com/id/docs/images/configure-with-ai/admin-api-keys-03-activity.webp)

## Verifikasi {#verify}

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

```bash
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:

```bash
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](https://nexcmp.com/id/docs/configure-with-ai/mcp-admin/).

## Galat {#errors}

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 {#limits-notes}

- 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](https://nexcmp.com/id/docs/configure-with-ai/oauth-connectors/)).