---
title: Admin API keys
description: 為AI代理與指令碼建立和撤銷ak_管理員金鑰：八種權限範圍、到期日、IP範圍、速率限制、金鑰絕對無法執行的動作以及所有錯誤代碼。
url: https://nexcmp.com/zh-tw/docs/configure-with-ai/admin-api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Admin API keys {#admin-api-keys}

> **後台位置：** System › Settings › API & AI agents (`/agent/keys`)，分頁 **API keys**。同頁面亦包含 **Connect an AI**、**Connected apps** 與 **Activity** 分頁。

## 功能 {#what-it-does}

管理員API金鑰（前綴為 `ak_`）可讓AI用戶端或指令碼以您授予的精確權限管理您的面板。它適用於 `/v1/admin/` 的管理員API以及管理員MCP端點 `/mcp/admin`。它在其他任何地方皆不適用。

::: info 與客戶金鑰不同
客戶在客戶入口網站中建立以 `vk_` 開頭的金鑰（[API keys and scopes](https://nexcmp.com/zh-tw/docs/developers/api-keys/)）。這些金鑰僅能存取客戶 API 與 `/mcp`。客戶 API 會拒絕 `ak_` 金鑰，而管理員 API 會拒絕 `vk_` 金鑰。
:::

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 角色 | 您必須登入管理員帳號。金鑰無法建立其他金鑰。 |
| Demo | 在展示面板上此頁面為唯讀：無法建立或撤銷任何金鑰。 |
| Reachability | 用戶端必須能夠連線至您面板上的 `https://cloud.example.com/mcp/admin` 或 `/v1/admin/...`（若您使用IP限制，請檢查防火牆設定）。 |

## Create a key {#create-a-key}

1. 開啟 **System › Settings › API & AI agents** 並停留在 **API keys** 分頁。
2. 點擊 **Create new key**。
3. 填寫表單：

   | 欄位 | 規則 |
   |---|---|
   | Name | 最多60個字元，例如 "Claude Code on my laptop"。 |
   | Scopes | 請勾選至少一項。請參閱 [Scopes](#scopes)。建議最初僅使用 `admin:read`。 |
   | Expiry | 1、7、30、60或90天。預設為30。上限為90。無法建立未設定到期日的金鑰。 |
   | IP ranges (optional) | 每行一個IPv4、IPv6位址或CIDR，例如 `203.0.113.0/24` 或 `2001:db8::/48`。最多32個。留空則允許所有IP。 |
   | Calls per minute | 1 to 6000. Default 120. |

4. 點擊 **Create key**。對話方塊會顯示金鑰一次，例如 `ak_XXXX`。**請立即複製**：NexCMP僅儲存雜湊值，且絕無法再次顯示。
5. 點擊 **I have saved the key**。開啟 **Connect an AI** 分頁即可取得內含您剛剛建立之金鑰的隨貼即用指令（僅在此頁面有效，直到您重新載入頁面為止）。

![填入名稱、權限範圍核取方塊、到期日與IP範圍的新金鑰對話方塊](https://nexcmp.com/zh-tw/docs/images/configure-with-ai/admin-api-keys-01-create.webp)

![顯示新金鑰一次並附帶複製按鈕與警告的對話方塊](https://nexcmp.com/zh-tw/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp)

## Scopes {#scopes}

金鑰僅能使用其權限範圍所允許的工具與端點。寫入權限不包含讀取存取權：需要同時讀取與寫入的金鑰也必須具備 `admin:read`。

| Scope | What it allows |
|---|---|
| `admin:read` | 讀取設定、目錄、客戶、帳務與記錄。絕不會傳回機密資料。 |
| `catalog:write` | 方案、作業系統範本、配額、折扣碼。 |
| `infra:write` | 基礎架構來源（CloudStack、Proxmox）、區域、伺服器。 |
| `billing:write` | 支付閘道、貨幣、發票、餘額。金錢相關動作需要確認。 |
| `customers:write` | 客戶與經銷商。 |
| `settings:write` | 一般設定、品牌、電子郵件、法律頁面、模組、通知。 |
| `ai:write` | AI 提供者與 AI 功能。 |
| `secrets:write` | 寫入密碼與 API 金鑰。它們可以被設定，但永遠無法被讀取出來。 |

::: tip 設定密鑰需要兩個範圍
任何攜帶密碼、API 金鑰或權杖值的呼叫（例如 SMTP 密碼、付款金鑰、Telegram Bot 權杖、AI 提供者金鑰、CloudStack 或 Proxmox 憑證）都需要 `secrets:write` **以及**該區域的範圍（例如針對 SMTP 的 `settings:write`）。如果您寧願自己手動輸入密鑰，請將 `secrets:write` 關閉並在管理後臺中輸入它們。
:::

## 撤銷金鑰 {#revoke-a-key}

1. 在表格中尋找該金鑰（狀態為 **Active**、**Expired** 或 **Revoked**；**Last used** 會顯示時間與客戶）。
2. 點擊 **Revoke** 並確認。

該金鑰會立即停止運作。撤銷動作是永久性的；若您需要再次使用，請建立一組新金鑰。

## 金鑰絕對無法執行的操作 {#what-a-key-can-never-do}

無論其範圍為何，金鑰永遠無法到達這些區域。這些區域需要您登入管理後臺。

- 建立或變更管理員使用者、2FA 與登入安全性、管理員工作階段，以及管理員 API 權杖。
- 建立、列出或撤銷管理員金鑰、OAuth 連線與 AI 帳戶，或使用 AI 主控台。
- 備份或還原面板、更新面板，或變更其授權。
- 以客戶或經銷商身分登入、開啟客戶的主控台、讀取虛擬機器憑證或 kubeconfig、設定 SSH 金鑰，或傳送或重設密碼。
- 變更網路與路由模組（BGP、FRR、RTBH、XDP、介面、靜態與原則路由、NAT）或外部代理程式與入口整合。這些皆為唯讀。
- 變更諸如 `demo_*`、`admin_*`、主機清單、通行金鑰、重新驗證與驗證碼密鑰等設定。

規則未涵蓋的任何內容，寫入預設為關閉，讀取則可使用 `admin:read`。

### 需要您確認的動作 {#actions-that-need-your-confirmation}

這些動作只有在您核准預覽後才會成功（請參閱 [Two-step confirmation](#two-step-confirmation)）：

- 變更客戶餘額或經銷商錢包、撥款、帳務記錄、匯率。
- 變更價格（方案價格、批次方案建立、映像檔與儲存定價）以及建立折扣或金額代碼。
- 儲存金流閘道憑證或 CloudStack 連線。
- 刪除任何項目、封鎖或刪除客戶、變更客戶的限制、暫停或關閉經銷商。
- 對客戶伺服器執行動作，或為客戶建立付費伺服器。
- 透過一般設定變更全站開關、登入安全性設定或付款設定。

## 雙步驟確認 {#two-step-confirmation}

當呼叫需要確認時，尚不會有任何變更。回應為 HTTP **428**，包含 `confirm_required`、`confirm_token`、`preview`（方法、路徑、原因、新值，以及在可用時的目前值）與 `expires_in: 300`。

1. 客戶端會向您顯示預覽。
2. 在您核准後，它會以標頭 `X-Confirm-Token: <confirm_token>` 重複發送**相同**的請求（相同的方法、路徑與內文）。MCP 工具則改為採用引數 `confirm_token`。
3. 該權杖僅能使用一次，並會在 5 分鐘後過期。

在管理後臺內為 AI Chat 建立的金鑰只能在畫面上確認：回應會顯示 `confirm_in: "ui"`，並且管理後臺中會出現確認卡片。AI 無法核准它。

## 速率限制與 IP 規則 {#rate-limit-and-ip-rules}

- 超過每分鐘限制時，呼叫會回傳 `rate_limited`（HTTP 429）以及 `Retry-After: 60`。
- 設定 IP 範圍後，來自任何其他位址的呼叫都會回傳 `ip_not_allowed`（HTTP 403）。

## 活動紀錄 {#activity-log}

**Activity** 標籤頁會列出使用金鑰進行的所有呼叫，由新到舊排序：時間、金鑰、客戶、來源方式（`http`、`mcp`、`chat`、`cli`、`confirm`、`preview`）、方法與路徑、工具、HTTP 狀態、IP 以及（遮罩後的）詳細資料。你可以依路徑、工具或金鑰名稱搜尋，僅顯示錯誤（HTTP 400 及以上）或僅顯示等待確認的呼叫（428 及以上），並將時間範圍限制在最近一小時、24 小時或 7 天。NexCMP 會保留最近 200,000 筆紀錄。透過金鑰所做的變更也會顯示在 Logs › Admin actions 中，並帶有 `ak:<admin>/<key name>` 名稱。

![Activity 標籤頁，列出包含狀態、客戶、工具與 IP 的呼叫](https://nexcmp.com/zh-tw/docs/images/configure-with-ai/admin-api-keys-03-activity.webp)

## 驗證 {#verify}

從 IP 範圍內的任何機器測試唯讀金鑰：

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

你將會取得一個包含你所允許之工具的 JSON 清單。執行其中一個：

```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 '{}'
```

金鑰的 **Last used** 時間會更新，且該呼叫會顯示在 **Activity** 中。完整的工具清單與 OpenAPI 描述（`/v1/admin/openapi.json`）說明於 [Connect an AI client](https://nexcmp.com/zh-tw/docs/configure-with-ai/mcp-admin/)。

## 錯誤 {#errors}

錯誤為 JSON 格式：`{"error": {"code": "...", "message": "..."}}`。

| HTTP | `code` | 含意 | 修正方式 |
|---|---|---|---|
| 401 | `invalid_key` | 金鑰遺失、格式錯誤或未知。在非管理員路徑上使用 `ak_` 金鑰時也會回傳此錯誤。 | 檢查金鑰；僅在 `/v1/admin/` 與 `/mcp/admin` 上使用。 |
| 401 | `key_expired` | 金鑰已過期。 | 建立新金鑰。 |
| 401 | `key_revoked` | 金鑰已被撤銷。 | 建立新金鑰。 |
| 403 | `ip_not_allowed` | 呼叫者的 IP 超出金鑰的 IP 範圍。 | 從允許的 IP 進行呼叫，或建立具有正確範圍的金鑰。 |
| 403 | `local_only_key` | 從其他機器使用了為 AI Chat 或伺服器 CLI 建立的金鑰。 | 這些金鑰僅適用於面板伺服器本身。 |
| 403 | `insufficient_scope` | 金鑰缺少範圍；回應包含 `required_scope`。 | 建立具有該範圍的金鑰。 |
| 403 | `forbidden_for_keys` | 端點或你嘗試變更的設定對金鑰關閉。 | 在管理員中執行此操作。 |
| 403 | `demo_read_only` | 面板處於展示模式且呼叫執行了寫入。 | 使用非展示模式的面板。 |
| 403 | `confirm_in_ui` | 此操作必須在管理員畫面上進行確認。 | 批准確認卡片。 |
| 428 | `confirm_required` | 預覽已準備就緒；沒有任何變更。包含 `confirm_token`。 | 顯示預覽，然後使用 `X-Confirm-Token` 重複操作。 |
| 409 | `confirm_expired` | 權杖已超過 5 分鐘。 | 重新發送請求以取得新的預覽。 |
| 409 | `confirm_mismatch` | 權杖屬於不同的請求（方法、路徑或內文不同）。 | 重複相同的請求。 |
| 409 | `confirm_invalid` | 未知或已使用的權杖。 | 重新發送請求以取得新的預覽。 |
| 429 | `rate_limited` | 本分鐘呼叫次數過多。 | 等待 `Retry-After`。 |
| 400 | `invalid_path` | 路徑包含禁止的序列。 | 使用單純的路徑。 |
| 413 | `too_large` | 內文超過 10 MB。 | 發送較少資料。 |
| 400 | `invalid_argument` | 工具引數遺失、未知或類型錯誤；訊息會指出該引數。 | 修正引數。 |

## 限制與注意事項 {#limits-notes}

- 保持金鑰短效且權限狹窄。建議每個客戶使用一支金鑰，以便單獨撤銷。
- 金鑰的功能強大程度取決於其範圍。`secrets:write` 搭配 `billing:write` 是最敏感的組合；金錢操作仍會在預覽階段停止。
- 自動建立的金鑰（用於 AI Chat、伺服器 CLI）僅存活幾分鐘，且只能從面板伺服器運作。
- 若要立即中斷 AI 客戶端，請撤銷其金鑰。OAuth 連線可在 **Connected apps** 分頁（[OAuth connectors](https://nexcmp.com/zh-tw/docs/configure-with-ai/oauth-connectors/)）中撤銷。