---
title: API 金鑰與範圍
description: 客戶如何建立 API 金鑰（vk_ 字首）、選擇範圍、依 IP 與有效期限限制，以及管理員如何審查和撤銷金鑰。
url: https://nexcmp.com/zh-tw/docs/developers/api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# API 金鑰與範圍 {#api-keys-and-scopes}

> **Portal 位置：** API keys (`/api-keys`)。**Admin 位置：** Customers › Customers › API keys (`/customers/apikeys`)。

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

**API key** 允許腳本、CI 作業、[`cmp` CLI](https://nexcmp.com/zh-tw/docs/developers/cmp-cli/) 或 AI 助理 ([MCP](https://nexcmp.com/zh-tw/docs/developers/mcp/)) 代表單一客戶呼叫 [REST API](https://nexcmp.com/zh-tw/docs/developers/api/)，且僅具備被授與的權限（**scopes**）。客戶金鑰以 `vk_` 開頭。它們可以讀取和管理服務，但**絕不能**觸及金錢或帳戶本身。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 客戶 | 已登入的 portal 工作階段（金鑰無法建立或編輯其他金鑰，冒充客戶的管理員亦然）。 |
| 切換開關 | API 金鑰預設為開啟。如果關閉，呼叫將回傳 401 `api_keys_disabled`。 |
| 相依項目 | 產品的範圍僅在該網站啟用該產品時才會顯示。 |

## 建立金鑰（客戶） {#create-a-key-customer}

1. 登入 portal 並開啟 **API keys**。
2. 按一下 **Create key**。
3. 填寫表單：

   | 欄位 | Rule |
   |---|---|
   | **Key name** | 必填，最多 60 個字元（例如「deploy server」、「backup script」）。 |
   | **此金鑰可執行的動作** | 勾選您需要的範圍 — 至少一個。唯讀金鑰不應取得任何寫入範圍。請小心涉及金錢或刪除資料的範圍。 |
   | **Expiry** | 永不過期、30 天、90 天或 1 年（API 接受 1 到 3650 天）。 |
   | **僅允許來自這些 IP 的呼叫** | 每行一個 IP 或 CIDR 範圍，最多 20 個（IPv4 或 IPv6）。留空表示任何 IP。只要可能，請綁定您伺服器的 IP。 |

4. 確認表單。金鑰會在一視窗中**僅顯示一次**「Key created — shown ONCE」。請複製它並按一下 **I saved the key**。系統僅儲存 SHA-256 雜湊，因此連管理員也無法再次讀取它；若您遺失它，請將其撤銷並建立新金鑰。
5. Portal 同時也會顯示一個現成的 `curl` 指令來測試金鑰。


金鑰看起來像 `vk_` 後接一長串隨機字串。列表僅顯示前幾個字元（例如 `vk_a1b2c3d4`）、範圍、有效期限、上次使用時間、請求次數與狀態 (*Active*、*Expired*、*Revoked*)。

### 編輯、撤銷、稽核 {#edit-revoke-audit}

- **Edit** 用於修改名稱、範圍、允許的 IP 與到期時間。模擬使用者作業階段期間不允許執行此操作。
- **Revoke**會立即停用金鑰且無法復原。系統會保留該資料列以確保使用記錄依然可查。
- **Key usage log** 顯示過去 60 天內的寫入指令與所有錯誤：時間、請求、金鑰、結果與來源 IP。
- 預設情況下，一個帳戶最多可持有 **10 個有效金鑰**。
- 透過 CLI 或 MCP 登入建立的金鑰會顯示在 **Connected apps & devices** 底下，並可在該處撤銷。

## Scopes {#scopes}

範圍名稱的格式為 `area:action`。提供的範圍取決於您啟用的產品。

| Scope | Allows |
|---|---|
| `catalog:read` | 讀取方案與目錄。 |
| `vm:read` | 讀取虛擬機器、指標與虛擬機器帳單。 |
| `vm:write` | 電源操作、微幅變更、防火牆、快速快照。 |
| `vm:create` | **建立虛擬機器（會產生費用）。** |
| `vm:plan` | **變更方案或調整大小（會產生費用）。** |
| `vm:destroy` | **刪除虛擬機器。** |
| `vm:restore` | **從快照還原虛擬機器（將覆寫磁碟）。** |
| `vm:console` | 開啟 VNC 主控台工單。 |
| `sshkey:read`, `sshkey:write` | 讀取、新增與移除 SSH Keys。 |
| `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | 資料磁碟區（建立與擴充會產生費用；銷毀會遺失資料）。 |
| `backup:read`, `backup:write`, `backup:restore` | Backups（還原將會覆寫磁碟）。 |
| `billing:read` | 錢包、發票、付款記錄 — **僅限讀取**。 |
| `bandwidth:buy` | **購買頻寬附加元件（會產生費用）。** |
| `account:read`, `account:write` | 個人資料、總覽、活動、通知；`account:write` 僅將通知標示為已讀。 |
| `apikey:read` | 列出帳戶的金鑰與使用記錄（無法建立、編輯或撤銷）。 |
| `apikey:self` | 每個金鑰的隱含權限：檢查呼叫端金鑰（`GET /v1/apikeys/self`）。 |
| `ticket:read`, `ticket:write` | 支援工單。 |
| `aff:read`, `transfer:read` | 聯盟計畫與服務轉移 — 僅限讀取。 |
| `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes（建立與擴展會產生費用；kubeconfig 具備 cluster-admin 權限）。 |
| `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | Private Cloud。 |
| `image:read`, `image:write` | 作業系統與 ISO 映像檔（儲存空間採按小時計費）。 |
| `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage（S3 金鑰僅顯示一次）。 |
| `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPN 與 IPv6 Proxy（連線詳細資料包含 Proxy 密碼）。 |
| `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | 實體伺服器（從錢包建立訂單；銷毀會重新安裝作業系統）。 |
| `shield:read`, `shield:write`, `shield:agent` | DDoS Shield，僅在啟用該模組時適用。 |

超出金鑰範圍的呼叫會回傳 **403 `scope_required`**；金鑰無權呼叫的路徑會回傳 **403 `endpoint_not_public`**。

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

任何範圍皆無法執行以下操作：加值或提領資金、變更信用卡或自動加值、變更密碼、電子郵件或 2FA、刪除帳戶、以及建立、編輯或撤銷其他金鑰。這些操作一律需要透過已登入的瀏覽器執行。即使金鑰遭洩漏，也無法碰觸客戶的資金或帳戶。

## 您可以信賴的規則 {#rules-you-can-rely-on}

| Rule | Detail |
|---|---|
| Site-bound | 金鑰僅在建立它的網站（網域）上有效。 |
| 速率限制 | 每個金鑰與每個帳戶：預設分別為每分鐘 120 次與 300 次請求。 |
| 冪等性 | 會產生費用或無法重複執行的操作需要 `Idempotency-Key` 標頭。 |
| 配額 | 金鑰受限於與客戶相同的 [quotas](https://nexcmp.com/zh-tw/docs/billing/quotas/)。 |
| Locked account | 已鎖定客戶的金鑰會停止運作（403 `account_blocked`）。 |
| 稽核 | 管理員執行的撤銷動作會寫入管理員稽核記錄。 |

## 管理員檢視 {#administrator-view}

1. 開啟 **Customers › API keys**（`/customers/apikeys`）。表格會顯示金鑰名稱與前幾個字元、擁有者、範圍、狀態、最後使用時間（時間、請求次數、IP）及到期日。
2. 若您有經銷商，可依站台篩選。亦可依名稱、ID 或金鑰開頭搜尋。
3. 點擊 **Revoke** 以停用現有金鑰，或點擊 **Log** 查看其使用記錄。
4. 管理員**可以檢視與撤銷**金鑰，但無法為客戶讀取或建立金鑰。

![客戶 API 金鑰的管理員清單，包含範圍、狀態、最後使用時間與 Revoke 按鈕](https://nexcmp.com/zh-tw/docs/images/developers/api-keys-02-admin.webp)

## 驗證 {#verify}

1. 建立僅包含範圍 `vm:read` 的金鑰。
2. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` 會傳回 VM 清單。
3. `curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX"` 會回應 403 `scope_required`。
4. 撤銷該金鑰後，再次呼叫會回應 401 `key_revoked`。

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

- 金鑰將不會再次顯示。請將其視為密碼，並妥善儲存於密碼管理員或 CI 密鑰中。
- 建議每個指令碼使用一支金鑰、縮小範圍、設定較短的到期日與 IP 允許清單；透過建立新金鑰並撤銷舊金鑰來進行輪替。
- 來自裝置登入（CLI、MCP）的金鑰預設為 90 天。
- 已刪除或轉移的資源不會受到撤銷金鑰的影響。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 錯誤 `too_many_keys` (422) | 已達到有效金鑰的上限（預設為 10 個） | 撤銷舊金鑰。 |
| 錯誤 `invalid_argument`：未選擇範圍 | 未勾選任何範圍 | 請至少勾選一個範圍。 |
| 允許的 IP 發生錯誤 `invalid_argument` | 條目不是 IP 或網段、字首長度錯誤，或者超過 20 個條目 | 每行一個 IP 或 CIDR，例如 `203.0.113.0/24`。 |
| 模擬登入期間拒絕建立 | `impersonate_forbidden` | 請要求客戶自行建立金鑰。 |
| 401 `key_expired` | 已過到期日 | 建立新金鑰。 |
| 401 `key_ip_denied` | 呼叫端 IP 不在允許清單中 | 新增 IP 或清除清單。 |
| 401 `api_keys_disabled` | 功能已關閉 | 請聯絡您的管理員（`api_keys_enabled` 設定）。 |