Admin API key

Vị trí trong admin: System › Settings › API & AI agents (/agent/keys), tab API keys. Trang này cũng có các tab Connect an AI, Connected apps và Activity.

Chức năng

Admin API key (tiền tố ak_) cho phép AI client hoặc script quản lý panel của bạn với đúng các quyền hạn mà bạn cấp. Key hoạt động trên admin API tại /v1/admin/ và endpoint admin MCP /mcp/admin. Key không thể sử dụng ở bất kỳ nơi nào khác.

Khác với customer key

Khách hàng tạo các key bắt đầu bằng vk_ trong customer portal (API keys and scopes). Các key đó chỉ truy cập được customer API và /mcp. Key ak_ sẽ bị từ chối trên customer API, và key vk_ sẽ bị từ chối trên admin API.

Yêu cầu

Hạng mục	Yêu cầu
Role	Bạn phải đăng nhập vào admin. Key không thể tự tạo các key khác.
Demo	Trên panel demo, trang này ở chế độ chỉ đọc: không thể tạo hoặc thu hồi key.
Khả năng kết nối	Client phải kết nối được tới `https://cloud.example.com/mcp/admin` hoặc `/v1/admin/...` trên panel của bạn (hãy kiểm tra firewall nếu bạn áp dụng giới hạn IP).

Tạo key

Mở System › Settings › API & AI agents và ở lại tab API keys.
Nhấp vào Create new key.

Điền thông tin vào biểu mẫu:

Trường	Quy tắc
Name	Tối đa 60 ký tự, ví dụ "Claude Code on my laptop".
Scope	Đánh dấu ít nhất một mục. Xem Scopes. Ban đầu chỉ nên chọn `admin:read`.
Thời hạn	1, 7, 30, 60 hoặc 90 ngày. Mặc định 30. Tối đa 90. Không thể tạo key không có thời hạn.
Dải IP (tùy chọn)	Mỗi dòng một địa chỉ IPv4, IPv6 hoặc CIDR, ví dụ `203.0.113.0/24` hoặc `2001:db8::/48`. Tối đa 32 mục. Để trống để cho phép mọi IP.
Số lượt gọi mỗi phút	1 đến 6000. Mặc định 120.

Nhấp vào Create key. Hộp thoại sẽ hiển thị key một lần duy nhất, ví dụ ak_XXXX. Hãy sao chép ngay: NexCMP chỉ lưu chuỗi hash và không thể hiển thị lại key.
Nhấp vào I have saved the key. Mở tab Connect an AI để lấy lệnh sẵn sàng dán đã chứa sẵn key bạn vừa tạo (chỉ hiển thị trên trang này cho đến khi bạn tải lại trang).

Scope

Một khóa chỉ có thể sử dụng các công cụ và endpoint mà phạm vi quyền (scopes) của nó cho phép. Quyền ghi không bao gồm quyền đọc: khóa cần cả đọc và ghi phải có thêm admin:read.

Scope	Quyền hạn
`admin:read`	Đọc cài đặt, danh mục, khách hàng, thanh toán và nhật ký. Không bao giờ trả về secret.
`catalog:write`	Gói cước, OS template, hạn mức, mã giảm giá.
`infra:write`	Nguồn hạ tầng (CloudStack, Proxmox), zone, server.
`billing:write`	Cổng thanh toán, tiền tệ, hóa đơn, số dư. Các thao tác liên quan đến tiền cần xác nhận.
`customers:write`	Khách hàng và đại lý.
`settings:write`	Cài đặt chung, thương hiệu, email, trang pháp lý, module, thông báo.
`ai:write`	Nhà cung cấp AI và các tính năng AI.
`secrets:write`	Ghi mật khẩu và API key. Có thể thiết lập nhưng không thể đọc lại.

Thiết lập secret cần hai phạm vi quyền

Bất kỳ lệnh gọi nào mang giá trị mật khẩu, API key hoặc token (mật khẩu SMTP, khóa thanh toán, bot token Telegram, khóa nhà cung cấp AI, thông tin đăng nhập CloudStack hoặc Proxmox) đều cần secrets:write và phạm vi quyền của khu vực tương ứng (ví dụ: settings:write cho SMTP). Nếu bạn muốn tự nhập secret, hãy bỏ chọn secrets:write và nhập trực tiếp trong trang quản trị.

Thu hồi khóa

Tìm khóa trong bảng (trạng thái Active, Expired hoặc Revoked; Last used hiển thị thời gian và client).
Nhấp vào Revoke và xác nhận.

Khóa sẽ ngừng hoạt động ngay lập tức. Thu hồi là vĩnh viễn; hãy tạo khóa mới nếu bạn cần sử dụng lại.

Những thao tác key không bao giờ có thể thực hiện

Khóa không bao giờ có thể truy cập các khu vực này, bất kể phạm vi quyền của nó là gì. Các khu vực này yêu cầu bạn phải đăng nhập vào trang quản trị.

Tạo hoặc thay đổi người dùng quản trị, 2FA và bảo mật đăng nhập, phiên đăng nhập quản trị và token admin API.
Tạo, liệt kê hoặc thu hồi khóa quản trị, kết nối OAuth và tài khoản AI, hoặc sử dụng AI Console.
Sao lưu hoặc khôi phục bảng điều khiển, cập nhật hoặc thay đổi giấy phép bản quyền.
Đăng nhập với tư cách khách hàng hoặc đại lý, mở console của khách hàng, đọc thông tin đăng nhập VM hoặc kubeconfig, thiết lập SSH Keys, hoặc gửi hay đặt lại mật khẩu.
Thay đổi các module mạng và định tuyến (BGP, FRR, RTBH, XDP, interface, static và policy route, NAT) hoặc agent bên ngoài và tích hợp cổng thông tin. Các mục này là chỉ đọc.
Thay đổi các cài đặt như demo_*, admin_*, danh sách máy chủ, passkey, secret dùng cho xác thực lại và captcha.

Bất kỳ mục nào không được quy định bởi một quy tắc đều mặc định bị chặn ghi, và có thể đọc bằng admin:read.

Hành động cần bạn xác nhận

Các hành động này chỉ thành công sau khi bạn phê duyệt bản xem trước (xem Xác nhận hai bước):

Thay đổi số dư của khách hàng hoặc ví đại lý, chi trả tiền, bản ghi thanh toán, tỷ giá hối đoái.
Thay đổi giá (giá gói cước, tạo gói hàng loạt, định giá image và lưu trữ) và tạo mã giảm giá hoặc mã nạp tiền.
Lưu thông tin đăng nhập cổng thanh toán hoặc kết nối CloudStack.
Xóa bất kỳ dữ liệu nào, chặn hoặc xóa khách hàng, thay đổi giới hạn của khách hàng, tạm ngừng hoặc đóng tài khoản đại lý.
Thao tác trên server của khách hàng, hoặc tạo server trả phí cho khách hàng.
Thay đổi các công tắc trên toàn hệ thống, cài đặt bảo mật đăng nhập hoặc cài đặt thanh toán thông qua cài đặt chung.

Xác nhận hai bước

Khi một lệnh gọi cần xác nhận, chưa có gì thay đổi. Phản hồi trả về mã HTTP 428 cùng confirm_required, confirm_token, preview (method, path, reason, các giá trị mới và các giá trị hiện tại nếu có) và expires_in: 300.

Client sẽ hiển thị bản xem trước cho bạn.
Sau khi bạn phê duyệt, nó sẽ lặp lại chính xác request đó (cùng method, path và body) với header X-Confirm-Token: <confirm_token>. Các công cụ MCP sẽ nhận đối số confirm_token thay thế.
Token chỉ dùng được một lần và hết hạn sau 5 phút.

Các key được tạo trong trang admin cho AI Chat chỉ có thể được xác nhận trên màn hình: phản hồi trả về confirm_in: "ui" và một thẻ xác nhận sẽ xuất hiện trong trang admin. AI không thể tự phê duyệt thao tác này.

Giới hạn tần suất và quy tắc IP

Vượt quá giới hạn mỗi phút, lệnh gọi sẽ trả về rate_limited (HTTP 429) cùng Retry-After: 60.
Khi đã thiết lập dải IP, các lệnh gọi từ bất kỳ địa chỉ nào khác sẽ trả về ip_not_allowed (HTTP 403).

Nhật ký hoạt động

Tab Activity liệt kê mọi lệnh gọi được thực hiện bằng key, mới nhất trước: thời gian, key, client, phương thức gửi đến (http, mcp, chat, cli, confirm, preview), method và path, tool, mã trạng thái HTTP, IP cùng chi tiết (đã che bớt). Bạn có thể tìm kiếm theo path, tool hoặc tên key, chỉ hiển thị lỗi (HTTP từ 400 trở lên) hoặc chỉ các lệnh gọi đang chờ xác nhận (từ 428 trở lên), và giới hạn khoảng thời gian trong 1 giờ, 24 giờ hoặc 7 ngày gần nhất. NexCMP lưu giữ 200,000 mục gần nhất. Các thay đổi được thực hiện qua key cũng xuất hiện trong Logs › Admin actions dưới tên ak:<admin>/<key name>.

Kiểm tra

Kiểm tra key chỉ đọc từ bất kỳ máy nào nằm trong dải IP:

bash

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

Bạn sẽ nhận được danh sách JSON các tool mà scope của bạn cho phép. Hãy chạy thử một tool:

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

Thời gian Last used của key được cập nhật và lệnh gọi xuất hiện trong Activity. Danh sách tool đầy đủ và mô tả OpenAPI (/v1/admin/openapi.json) được trình bày trong mục Kết nối AI client.

Lỗi

Lỗi có định dạng JSON: {"error": {"code": "...", "message": "..."}}.

HTTP	`code`	Ý nghĩa	Cách khắc phục
401	`invalid_key`	Key bị thiếu, sai định dạng hoặc không xác định. Cũng được trả về khi key `ak_` được sử dụng trên path không thuộc admin.	Kiểm tra lại key; chỉ sử dụng trên `/v1/admin/` và `/mcp/admin`.
401	`key_expired`	Key đã hết hạn.	Tạo một key mới.
401	`key_revoked`	Key đã bị thu hồi.	Tạo một key mới.
403	`ip_not_allowed`	IP của bên gọi nằm ngoài dải IP của key.	Gọi từ IP được cho phép, hoặc tạo key với dải IP phù hợp.
403	`local_only_key`	Key được tạo cho AI Chat hoặc server CLI đã được dùng từ một máy khác.	Các key này chỉ hoạt động trên chính panel server.
403	`insufficient_scope`	Key thiếu scope; phản hồi bao gồm `required_scope`.	Tạo key có scope đó.
403	`forbidden_for_keys`	Endpoint, hoặc thiết lập bạn đang cố thay đổi, không mở cho truy cập bằng key.	Thực hiện thao tác này trong trang admin.
403	`demo_read_only`	Panel đang ở chế độ demo và lệnh gọi này là thao tác ghi dữ liệu.	Sử dụng panel không phải bản demo.
403	`confirm_in_ui`	Hành động này phải được xác nhận trực tiếp trên màn hình trong trang admin.	Phê duyệt thẻ xác nhận.
428	`confirm_required`	Bản xem trước đã sẵn sàng; chưa có gì thay đổi. Bao gồm `confirm_token`.	Hiển thị bản xem trước, sau đó lặp lại với `X-Confirm-Token`.
409	`confirm_expired`	Token đã tồn tại quá 5 phút.	Gửi lại request để lấy bản xem trước mới.
409	`confirm_mismatch`	Token thuộc về một request khác (khác method, path hoặc body).	Lặp lại request giống hệt.
409	`confirm_invalid`	Token không xác định hoặc đã được sử dụng.	Gửi lại request để lấy bản xem trước mới.
429	`rate_limited`	Quá nhiều lệnh gọi trong phút này.	Chờ `Retry-After`.
400	`invalid_path`	Path chứa các chuỗi ký tự bị cấm.	Dùng đường dẫn thông thường.
413	`too_large`	Dung lượng body vượt quá 10 MB.	Gửi ít dữ liệu hơn.
400	`invalid_argument`	Thiếu, không xác định hoặc sai kiểu đối số của công cụ; thông báo lỗi sẽ chỉ rõ đối số đó.	Sửa lại đối số.

Hạn mức & lưu ý

Hãy đặt thời hạn khóa ngắn và giới hạn phạm vi hẹp. Nên dùng mỗi client một khóa riêng để bạn có thể thu hồi từng khóa đơn lẻ.
Khóa có quyền hạn tương ứng với các scope của nó. secrets:write cùng billing:write là sự kết hợp nhạy cảm nhất; các tác vụ liên quan đến tiền vẫn sẽ dừng lại ở bước xem trước.
Các khóa được tạo tự động (cho AI Chat, server CLI) chỉ tồn tại trong vài phút và chỉ hoạt động từ chính server của panel.
Để ngắt kết nối client AI ngay lập tức, hãy thu hồi khóa của nó. Các kết nối OAuth được thu hồi tại tab Connected apps (OAuth connectors).

Admin API key ​

Chức năng ​

Yêu cầu ​

Tạo key ​

Scope ​

Thu hồi khóa ​

Những thao tác key không bao giờ có thể thực hiện ​

Hành động cần bạn xác nhận ​

Xác nhận hai bước ​

Giới hạn tần suất và quy tắc IP ​

Nhật ký hoạt động ​

Kiểm tra ​

Lỗi ​

Hạn mức & lưu ý ​