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。ak_ 密钥在客户 API 上会被拒绝，而 vk_ 密钥在管理 API 上会被拒绝。

前提条件

项目	要求
角色	您必须登录到管理后台。密钥无法创建其他密钥。
演示	在演示面板上，此页面为只读：无法创建或撤销任何密钥。
可达性	客户端必须能够访问您面板上的 `https://cloud.example.com/mcp/admin` 或 `/v1/admin/...`（如果您使用了 IP 限制，请检查您的防火墙）。

创建密钥

打开 System › Settings › API & AI agents 并停留在 API keys 标签页上。
点击 Create new key。

填写表单：

字段	规则
名称	最多 60 个字符，例如 "Claude Code on my laptop"。
权限范围	勾选至少一个。参见 Scopes。最初请仅选择 `admin:read`。
过期时间	1、7、30、60 或 90 天。默认 30。最大 90。无法创建没有过期时间的密钥。
IP 范围（可选）	每行一个 IPv4 或 IPv6 地址或 CIDR，例如 `203.0.113.0/24` 或 `2001:db8::/48`。最多 32 个。留空则允许任何 IP。
每分钟调用次数	1 到 6000。默认 120。

点击 Create key。一个对话框会显示一次该密钥，例如 ak_XXXX。请立即复制：NexCMP 仅存储哈希值，且绝不会再次显示它。
点击 I have saved the key。打开 Connect an AI 标签页即可获取现成可粘的命令，其中已经包含了您刚刚创建的密钥（仅在此页面上有效，直到您刷新页面）。

权限范围

API Key 仅可使用其权限范围（scopes）允许的工具和端点。写权限不包含读权限：需要读写功能的 Key 同时还需包含 admin:read。

权限范围	允许的操作
`admin:read`	读取设置、目录、客户、账单与日志。系统绝不会返回密钥（Secrets）。
`catalog:write`	套餐、操作系统模板、配额、折扣码。
`infra:write`	基础设施源（CloudStack、Proxmox）、可用区、服务器。
`billing:write`	支付网关、货币、账单、余额。资金相关操作需要确认。
`customers:write`	客户和分销商。
`settings:write`	常规设置、品牌、电子邮件、法律页面、模块、通知。
`ai:write`	AI提供商与AI功能。
`secrets:write`	写入密码和API密钥。可以设置但永远无法读取。

设置密钥需要两个作用域

任何携带密码、API密钥或令牌值的调用（例如SMTP密码、支付密钥、Telegram机器人令牌、AI提供商密钥、CloudStack或Proxmox凭据）都需要secrets:write以及该区域的作用域（例如用于SMTP的settings:write）。如果您更愿意自行手动输入密钥，请不要勾选secrets:write并在管理后台中输入。

吊销密钥

在表格中找到该密钥（状态为Active、Expired或Revoked；Last used会显示时间和客户端）。
点击Revoke并确认。

密钥将立即停止工作。吊销操作是永久性的；如需再次使用，请创建新密钥。

密钥绝无权限执行的操作

无论拥有何种作用域，密钥永远无法访问这些区域。这些操作需要您登录管理后台。

创建或修改管理员用户、2FA和登录安全性、管理员会话以及管理员API令牌。
创建、列出或吊销管理员密钥、OAuth连接和AI账户，或使用AI Console。
备份或恢复面板、更新面板或更改其许可证。
以客户或分销商身份登录、打开客户控制台、读取虚拟机凭据或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。

客户端会向您展示预览。
在您批准后，客户端会使用带有X-Confirm-Token: <confirm_token>标头的相同请求（相同的方法、路径和正文）重新发送。MCP工具则改用参数confirm_token。
该令牌仅可使用一次，并在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 条记录。通过密钥进行的更改也会以 ak:<admin>/<key name> 的名义显示在 Logs › Admin actions 中。

验证

在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中说明。

错误

错误信息为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客户端，请吊销其密钥。可以在Connected apps标签页（OAuth connectors）中吊销OAuth连接。

Admin API keys ​

功能说明 ​

前提条件 ​

创建密钥 ​

权限范围 ​

吊销密钥 ​

密钥绝无权限执行的操作 ​

需要您确认的操作 ​

两步确认 ​

速率限制与IP规则 ​

活动日志 ​

验证 ​

错误 ​

限制与注意事项 ​