@digiforce-nc/plugin-api-keys

Plugin quản lý API keys cho tích hợp bên ngoài — tạo token JWT gắn với role, cho phép hệ thống bên ngoài gọi API mà không cần đăng nhập qua giao diện.

Plugin này làm gì?

Khi cần tích hợp hệ thống bên ngoài (CI/CD, webhook, script tự động), thay vì dùng username/password, admin tạo API key gắn với role cụ thể. Hệ thống bên ngoài dùng key này làm Bearer token để gọi API.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Tạo API key	Ký JWT chứa role, thời hạn, lưu vào DB (token ẩn sau khi tạo)
2	Xác thực request	Request mang Bearer token → xác minh JWT → gắn role vào context
3	Quản lý vòng đời	Xóa key = block token, liệt kê keys của user hiện tại

Kiến trúc

Luồng tạo API key

Luồng sử dụng API key

Database - bảng apiKeys

Field	Mô tả
`name`	Tên mô tả key (ví dụ: "CI/CD Pipeline")
`roleName`	Role gắn với key — quyết định quyền truy cập
`expiresIn`	Thời hạn token ("30d", "1y", "never")
`token`	JWT — chỉ hiển thị 1 lần khi tạo, sau đó ẩn

Vòng đời plugin

ACL - Phân quyền

ACL snippet	Quyền	Mô tả
`pm.api-keys.configuration`	Admin	Truy cập trang API Keys trong Settings

Middleware bổ sung: user chỉ thấy và xóa được API keys do chính mình tạo.

Ví dụ sử dụng API

Tạo API key

typescript

const response = await agent.resource('apiKeys').create({
  values: { name: 'CI/CD Pipeline', roleName: 'editor', expiresIn: '30d' },
});
const { token } = response.body.data;
// lưu lại ngay, không hiển thị lại

Sử dụng từ bên ngoài

bash

curl -H "Authorization: Bearer eyJhbGciOi..." https://your-app.com/api/posts:list

Xóa API key (block token)

typescript

await agent.resource('apiKeys').destroy({ filterByTargetKey: keyId });

Thành phần client

Thành phần	Mô tả
`APIKeysConfiguration`	Trang Settings → Configuration quản lý API keys
`CreateAPIKeyForm`	Form tạo API key (chọn name, role, thời hạn)
`APIKeysList`	Danh sách keys của user hiện tại

Dependencies

Package	Vai trò
`@digiforce-nc/server`	Server framework — resource, middleware
`@digiforce-nc/database`	Database ORM — collection definitions
`@digiforce-nc/client`	Client framework — Settings UI
`@digiforce-nc/auth`	Auth module — JWT signing/verification