API key và scope

Vị trí trong portal: API keys (/api-keys). Vị trí trong admin: Customers › Customers › API keys (/customers/apikeys).

Chức năng

API key cho phép một script, CI job, cmp CLI hoặc trợ lý AI (MCP) gọi REST API thay mặt cho một khách hàng, chỉ với các quyền hạn (scope) đã được cấp. Khóa của khách hàng bắt đầu bằng vk_. Chúng có thể đọc và quản lý các dịch vụ nhưng không bao giờ được can thiệp vào tiền tệ hoặc chính tài khoản đó.

Yêu cầu

Hạng mục	Yêu cầu
Khách hàng	Một phiên đăng nhập portal (khóa không thể tạo hoặc chỉnh sửa các khóa khác, và quản trị viên đang mạo danh khách hàng cũng không thể).
Công tắc	API key được bật theo mặc định. Nếu bị tắt, các lượt gọi sẽ nhận phản hồi 401 api_keys_disabled.
Thành phần phụ thuộc	Các scope của một sản phẩm chỉ xuất hiện khi sản phẩm đó được bật trên trang.

Tạo khóa (khách hàng)

1. Đăng nhập vào portal và mở API keys.

2. Nhấp vào Create key.

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

   Trường	Quy tắc
   Key name	Bắt buộc, tối đa 60 ký tự ("deploy server", "backup script").
   Key này có thể làm gì	Chọn các scope bạn cần — tối thiểu một scope. Khóa chỉ đọc không nên nhận bất kỳ scope ghi nào. Hãy cẩn trọng với các scope phát sinh chi phí hoặc xóa dữ liệu.
   Expiry	Never, 30 ngày, 90 ngày hoặc 1 năm (API chấp nhận từ 1 đến 3650 ngày).
   Chỉ cho phép lệnh gọi từ các IP này	Mỗi dòng một IP hoặc dải CIDR, tối đa 20 (IPv4 hoặc IPv6). Để trống nghĩa là mọi IP. Hãy ghim IP máy chủ của bạn bất cứ khi nào có thể.

4. Xác nhận biểu mẫu. Khóa được hiển thị một lần duy nhất trong cửa sổ "Key created — shown ONCE". Hãy sao chép khóa và nhấp vào I saved the key. Hệ thống chỉ lưu mã băm SHA-256 nên ngay cả quản trị viên cũng không thể đọc lại khóa; nếu làm mất, bạn cần thu hồi và tạo khóa mới.

5. Portal cũng hiển thị sẵn một lệnh curl để kiểm tra khóa.

Khóa có tiền tố vk_ theo sau bởi một chuỗi ký tự ngẫu nhiên dài. Danh sách chỉ hiển thị các ký tự đầu tiên (ví dụ vk_a1b2c3d4), scope, thời hạn hết hạn, lần sử dụng gần nhất, số lượng yêu cầu và trạng thái (Active, Expired, Revoked).

Chỉnh sửa, thu hồi, audit

• Edit dùng để thay đổi tên, scope, các IP được phép và thời hạn. Thao tác này không được phép trong phiên mạo danh.
• Revoke dừng hoạt động của khóa ngay lập tức và không thể hoàn tác. Dòng này vẫn được giữ lại để nhật ký sử dụng của khóa tiếp tục khả dụng.
• Key usage log hiển thị các lệnh ghi và mọi lỗi trong 60 ngày gần nhất: thời gian, yêu cầu, khóa, kết quả và IP nguồn.
• Một tài khoản có thể giữ tối đa 10 khóa đang hoạt động theo mặc định.
• Các khóa được tạo qua đăng nhập CLI hoặc MCP sẽ xuất hiện tại Connected apps & devices và có thể thu hồi tại đó.

Scope

Tên scope có dạng area:action. Các scope khả dụng sẽ phụ thuộc vào những sản phẩm mà bạn đã bật.

Scope	Cho phép
catalog:read	Xem các gói dịch vụ và danh mục.
vm:read	Xem VM, chỉ số và hóa đơn VM.
vm:write	Tác vụ nguồn, thay đổi nhỏ, firewall, Snapshots nhanh.
vm:create	Tạo VM (phát sinh chi phí).
vm:plan	Đổi gói hoặc đổi kích thước (phát sinh chi phí).
vm:destroy	Xóa VM.
vm:restore	Khôi phục VM từ snapshot (ghi đè ổ đĩa).
vm:console	Mở ticket console VNC.
sshkey:read, sshkey:write	Xem, thêm và xóa SSH Keys.
volume:read, volume:write, volume:create, volume:destroy	Data volume (tạo và mở rộng sẽ phát sinh chi phí; hủy sẽ mất dữ liệu).
backup:read, backup:write, backup:restore	Backups (khôi phục sẽ ghi đè ổ đĩa).
billing:read	Ví, hóa đơn, lịch sử thanh toán — chỉ đọc.
bandwidth:buy	Mua add-on băng thông (phát sinh chi phí).
account:read, account:write	Hồ sơ, tổng quan, hoạt động, thông báo; account:write chỉ đánh dấu thông báo là đã đọc.
apikey:read	Liệt kê các khóa của tài khoản và nhật ký sử dụng (không thể tạo, sửa hoặc thu hồi).
apikey:self	Mặc định trên mọi khóa: kiểm tra khóa đang gọi (GET /v1/apikeys/self).
ticket:read, ticket:write	Ticket hỗ trợ.
aff:read, transfer:read	Chương trình affiliate và chuyển nhượng dịch vụ — chỉ đọc.
k8s:read, k8s:write, k8s:create, k8s:scale, k8s:destroy, k8s:kubeconfig	Kubernetes (tạo và mở rộng quy mô phát sinh chi phí; kubeconfig có quyền cluster-admin).
vpc:read, vpc:write, vpc:create, vpc:destroy	Private Cloud.
image:read, image:write	Image OS và ISO (dung lượng lưu trữ được tính phí theo giờ).
s3:read, s3:write, s3:create, s3:destroy, s3:keys	Object Storage (S3 secret chỉ được hiển thị một lần).
vpn:read, vpn:detail, vpn:write, vpn:create, vpn:destroy	VPN và proxy IPv6 (thông tin kết nối bao gồm mật khẩu proxy).
dedicated:read, dedicated:write, dedicated:console, dedicated:create, dedicated:destroy	Máy chủ Dedicated (tạo đơn hàng từ ví; hủy sẽ cài đặt lại OS).
shield:read, shield:write, shield:agent	DDoS Shield, chỉ khả dụng khi module đó được bật.

Lệnh gọi ngoài scope của key sẽ trả về 403 scope_required; đường dẫn mà không key nào có thể gọi sẽ trả về 403 endpoint_not_public.

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

Không scope nào cho phép: nạp hoặc rút tiền, đổi thẻ hoặc tự động nạp tiền, đổi mật khẩu, email hoặc 2FA, xóa tài khoản, tạo, sửa hoặc thu hồi key khác. Các thao tác này luôn cần trình duyệt đã đăng nhập. Ngay cả khi bị lộ, key cũng không thể can thiệp vào tiền hay tài khoản của khách hàng.

Các quy tắc bạn có thể tin cậy

Quy tắc	Chi tiết
Gắn liền với site	Key chỉ hoạt động trên site (tên miền) nơi key được tạo.
Rate limit	Mỗi key và mỗi tài khoản: mặc định 120 và 300 request mỗi phút.
Idempotency	Các thao tác tốn phí hoặc không thể lặp lại cần có header Idempotency-Key.
Quotas	Key phải tuân theo cùng quotas với khách hàng.
Tài khoản bị khóa	Các key của khách hàng bị khóa sẽ ngừng hoạt động (403 account_blocked).
Audit	Hành động thu hồi của quản trị viên được ghi vào admin audit log.

Giao diện quản trị viên

1. Mở Customers › API keys (/customers/apikeys). Bảng hiển thị tên key và các ký tự đầu, chủ sở hữu, scopes, trạng thái, lần dùng gần nhất (thời gian, số lượng request, IP), hạn dùng.
2. Lọc theo site nếu bạn có reseller. Tìm kiếm theo tên, ID hoặc phần đầu của key.
3. Nhấp Revoke để vô hiệu hóa một key đang hoạt động, hoặc Log để xem lịch sử sử dụng.
4. Quản trị viên xem và thu hồi key nhưng không thể đọc hay tạo key thay cho khách hàng.

Kiểm tra

1. Tạo một key chỉ có scope vm:read.
2. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" trả về danh sách VM.
3. curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX" trả về 403 scope_required.
4. Thu hồi key; lệnh gọi đầu tiên lúc này sẽ trả về 401 key_revoked.

Hạn mức & lưu ý

• Key sẽ không bao giờ hiển thị lại. Hãy xử lý nó như mật khẩu và lưu trữ trong secret manager hoặc CI secret.
• Nên dùng mỗi script một key, scopes tối thiểu, hạn dùng ngắn và allowlist IP; xoay vòng key bằng cách tạo key mới và thu hồi key cũ.
• Key từ đăng nhập thiết bị (CLI, MCP) có hạn mặc định là 90 ngày.
• Các tài nguyên đã xóa hoặc đã chuyển nhượng không bị ảnh hưởng khi thu hồi key.

Xử lý sự cố

Hiện tượng	Nguyên nhân	Cách khắc phục
Lỗi too_many_keys (422)	Đã đạt giới hạn số key đang hoạt động (mặc định 10)	Thu hồi một key cũ.
Lỗi invalid_argument: chưa chọn scope	Chưa tích chọn scope nào	Tích chọn ít nhất một scope.
Lỗi invalid_argument ở IP được phép	Một mục không phải IP hoặc dải IP, sai độ dài prefix, hoặc có hơn 20 mục	Mỗi dòng một IP hoặc CIDR, ví dụ 203.0.113.0/24.
Thao tác tạo bị từ chối khi đang impersonate	impersonate_forbidden	Yêu cầu khách hàng tự tạo key.
401 key_expired	Đã quá hạn sử dụng	Tạo một key mới.
401 key_ip_denied	IP của bên gọi không nằm trong allowlist	Thêm IP vào hoặc xóa danh sách.
401 api_keys_disabled	Tính năng đang tắt	Liên hệ quản trị viên của bạn (cài đặt api_keys_enabled).