Hướng dẫn cài đặt và sử dụng — API Keys

Yêu cầu hệ thống

Server Digiforce đang chạy
Quyền Admin để truy cập trang cấu hình API Keys

Bước 1: Kích hoạt plugin

Vào Settings → Plugin Manager, tìm plugin-api-keys và bật. Khởi động lại server.

Bước 2: Tạo API Key

Vào Settings → API Keys, nhấn Create:

Trường	Mô tả	Bắt buộc
Name	Tên mô tả cho key (ví dụ: "CI/CD Pipeline", "Webhook Integration")	Có
Role	Role gán cho key — quyết định quyền truy cập API	Có
Expires In	Thời hạn token: `30d`, `90d`, `1y`, `never`	Có

Quy trình tạo key

Quan trọng

API key chỉ hiển thị một lần duy nhất ngay sau khi tạo. Copy và lưu trữ an toàn ngay lập tức. Sau khi đóng dialog, không thể xem lại key.

Bước 3: Sử dụng API Key

Hệ thống bên ngoài gửi API request kèm key trong header:

bash

# Sử dụng Authorization header (khuyến nghị)
curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://your-domain/api/posts:list

Luồng xác thực

API key kế thừa toàn bộ quyền của role được gán. Ví dụ:

Role gán cho key	Quyền truy cập
`api-readonly`	Chỉ đọc dữ liệu (list, get)
`editor`	Đọc và ghi (create, update)
`admin`	Toàn quyền (bao gồm cả cấu hình)

Bước 4: Quản lý API Keys

Thao tác	Mô tả	Ghi chú
Xem danh sách	Tất cả keys của bạn (key value bị ẩn)	Chỉ thấy keys do mình tạo
Xoá key	Xoá vĩnh viễn — token ngay lập tức mất hiệu lực	Không thể hoàn tác

Middleware bảo mật

Plugin tự động thêm middleware đảm bảo mỗi user chỉ thấy và xoá được API keys do chính mình tạo. Admin cũng không thể xem keys của user khác.

Các trường hợp sử dụng phổ biến

Tích hợp CI/CD

bash

# GitHub Actions: gọi API để trigger deployment
curl -X POST \
  -H "Authorization: Bearer $DIGIFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  https://your-domain/api/deployments:create

Webhook từ hệ thống khác

bash

# Zapier/n8n gọi API để tạo bản ghi
curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": {"title": "New Lead", "status": "open"}}' \
  https://your-domain/api/leads:create

Script tự động hoá

python

import requests

headers = {"Authorization": "Bearer dk_xxxxx..."}
response = requests.get(
    "https://your-domain/api/orders:list",
    headers=headers,
    params={"pageSize": 50}
)
data = response.json()

Thực hành bảo mật tốt nhất

Thực hành	Lý do
Tạo role riêng với quyền tối thiểu cho API key	Giới hạn thiệt hại nếu key bị lộ
Không chia sẻ key qua email hoặc chat	Dùng secret manager (Vault, AWS Secrets)
Đặt thời hạn hợp lý	Integration lâu dài: 6–12 tháng; testing: 7–30 ngày
Xoay key định kỳ	Tạo key mới → cập nhật ứng dụng → xoá key cũ
Theo dõi sử dụng	Kết hợp audit logs để phát hiện bất thường
Key bị lộ → xoá ngay	Xoá key tức thì vô hiệu hoá token JWT

Lưu ý

API key có quyền theo role được gán — nên tạo role riêng với quyền tối thiểu
Key hết hạn tự động bị từ chối — request trả về 401 Unauthorized
Rate limit áp dụng như user bình thường
Plugin sử dụng JWT do @digiforce-nc/auth ký — cùng cơ chế xác thực với session token