API

Tạo token API tại Tài khoản → Token API (token đầy đủ chỉ hiển thị một lần). Gửi token dưới dạng Bearer header trong mỗi yêu cầu. Mỗi token chỉ có quyền với dịch vụ và thao tác bạn chọn, đồng thời vẫn tuân theo hạn mức gói. Hãy giữ bí mật và thu hồi ngay nếu token bị lộ.

Authorization: Bearer htx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

URL gốc: https://portal.vinacis.com · Đặc tả cho máy đọc: /api/openapi (OpenAPI 3.1)

Liệt kê cơ sở dữ liệu của bạn:

curl -H "Authorization: Bearer $HTX_TOKEN" \
  https://portal.vinacis.com/api/portal/databases

Tạo cơ sở dữ liệu PostgreSQL:

curl -X POST https://portal.vinacis.com/api/portal/databases \
  -H "Authorization: Bearer $HTX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"analytics","engine":"postgresql","sku":"db-s-1vcpu-2gb"}'

Xem một cơ sở dữ liệu, bắt đầu sao lưu hoặc xóa:

curl -H "Authorization: Bearer $HTX_TOKEN" https://portal.vinacis.com/api/portal/databases/analytics
curl -X POST -H "Authorization: Bearer $HTX_TOKEN" https://portal.vinacis.com/api/portal/databases/analytics/backups
curl -X DELETE -H "Authorization: Bearer $HTX_TOKEN" https://portal.vinacis.com/api/portal/databases/analytics

# Functions serverless
curl -H "Authorization: Bearer $HTX_TOKEN" https://portal.vinacis.com/api/portal/functions

# Tạo function công khai (visibility mặc định là public)
curl -X POST https://portal.vinacis.com/api/portal/functions \
  -H "Authorization: Bearer $HTX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"api","image":"ghcr.io/acme/api:release","sku":"fn-s-1"}'

# Cập nhật image và thay thế biến môi trường dạng thường trong cùng một lần triển khai
curl -X PATCH https://portal.vinacis.com/api/portal/functions/api \
  -H "Authorization: Bearer $HTX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image":"ghcr.io/acme/api@sha256:0123456789abcdef","env":{"APP_ENV":"production"}}'

# Proxy SOCKS5
curl -H "Authorization: Bearer $HTX_TOKEN" https://portal.vinacis.com/api/portal/proxies

Image của function có thể dùng tag hoặc @sha256: digest từ bất kỳ Registry nào. Nên dùng digest cho CD. Image riêng tư tại registry.fn.vinacis.com/<tenant>/... cần thông tin đăng nhập Registry; PATCH sẽ gắn pull secret tương ứng vào function hiện có.

Đặt visibility thành cluster-local khi tạo function hoặc cập nhật bằng PATCH để function không thể truy cập từ Internet. Đây không phải là cơ chế tách biệt khách hàng: tất cả function của khách hàng dùng chung một Kubernetes namespace. Không thể chuyển function sang chế độ cluster-local nếu function đang bật lịch chạy hoặc có custom domain hoạt động.

Các thao tác dịch vụ của khách hàng dùng route bên dưới /api/portal/* và chấp nhận cùng một bearer token. Quản lý tài khoản hoặc token, API dành cho quản trị viên và reseller, cùng các thay đổi thanh toán đều yêu cầu đăng nhập tương tác và không dành cho service token.

Chọn tổ hợp thao tác phù hợp cho từng dịch vụ:

• Dịch vụ: cơ sở dữ liệu, functions, proxy, cloud, ứng dụng, registry, bảo mật web và thông báo.
• Thao tác: đọc, thêm, sửa và xóa.
• Các thao tác như thay đổi cấu hình, nâng cấp, thử lại, bật hoặc đổi token dùng quyền sửa. Tạo bản sao lưu, cơ sở dữ liệu con, người dùng, lịch chạy, tên miền và bản triển khai dùng quyền thêm.

Yêu cầu nằm ngoài đúng phạm vi quyền của token sẽ trả về 403. Mọi route API của portal đều được kiểm tra phạm vi tự động; route mới chưa phân loại sẽ bị từ chối. Mỗi token có giới hạn tần suất (mặc định 120 yêu cầu/phút); vượt giới hạn sẽ trả về 429 kèm header Retry-After. Đổi token tại Nhà phát triển → Token API để nhận mã bí mật mới với cùng tên và quyền; mã cũ sẽ hết hiệu lực ngay.

Danh sách IP được phép (nên dùng): khi tạo token, hãy giới hạn token theo địa chỉ IPv4, IPv6 hoặc dải IPv4 CIDR cụ thể. Mọi endpoint sẽ từ chối IP nguồn khác, nên token của server hoặc CI bị lộ cũng không dùng được ngoài mạng của bạn. IP khách được lấy tại edge và không thể giả mạo bằng request header.

Quản lý các tài nguyên phổ biến dưới dạng mã bằng htx Terraform provider và htxcli CLI (cả hai đều xác thực bằng HTX_TOKEN):

resource "htx_database" "app" {
  name           = "app-db"
  engine         = "postgresql"
  sku            = "db-s-1vcpu-1gb"
  wait_for_ready = true
}

htxcli databases list
htxcli functions logs api --lines 100

# Truy cập chung cho mọi route dịch vụ khách hàng được hỗ trợ
htxcli api request GET /api/portal/cloud/servers
htxcli api request PATCH /api/portal/cloud/ssh-keys/key-1 \
  --data '{"name":"production"}'

• Token tuân theo hạn mức gói; script không thể tạo nhiều hơn mức portal cho phép.
• Bạn có thể thu hồi hoặc đổi token bất cứ lúc nào tại Tài khoản → Token API. Cả hai thao tác có hiệu lực ngay.
• Việc tạo, thu hồi hoặc đổi token yêu cầu đăng nhập trên trình duyệt và không thể thực hiện bằng một token khác.
• Token cũ giữ phạm vi trước đây trên các route dịch vụ khách hàng; các nhóm route được bảo vệ vẫn không khả dụng. Hãy đổi token cũ để nhận token có quyền chi tiết.