Admin API keys

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

功能

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

與客戶金鑰不同

客戶在客戶入口網站中建立以 vk_ 開頭的金鑰（API keys and scopes）。這些金鑰僅能存取客戶 API 與 /mcp。客戶 API 會拒絕 ak_ 金鑰，而管理員 API 會拒絕 vk_ 金鑰。

需求

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

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。建議最初僅使用 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 分頁即可取得內含您剛剛建立之金鑰的隨貼即用指令（僅在此頁面有效，直到您重新載入頁面為止）。

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 金鑰。它們可以被設定，但永遠無法被讀取出來。

設定密鑰需要兩個範圍

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

撤銷金鑰

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

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

金鑰絕對無法執行的操作

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

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

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

需要您確認的動作

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

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

雙步驟確認

當呼叫需要確認時，尚不會有任何變更。回應為 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_limited（HTTP 429）以及 Retry-After: 60。
• 設定 IP 範圍後，來自任何其他位址的呼叫都會回傳 ip_not_allowed（HTTP 403）。

活動紀錄

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

驗證

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

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

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

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。

錯誤

錯誤為 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	工具引數遺失、未知或類型錯誤；訊息會指出該引數。	修正引數。

限制與注意事項

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