Tham chiếu API — API Keys

Tổng quan Resource

Resource	Mô tả	Quyền
apiKeys	Quản lý API keys	Admin (pm.api-keys.configuration)

Middleware bổ sung: user chỉ thấy và xoá được API keys do chính mình tạo (scope filter theo userId).

Tạo API Key

const response = await agent.resource('apiKeys').create({
  values: {
    name: 'CI/CD Pipeline',
    roleName: 'editor',
    expiresIn: '30d',  // '30d', '90d', '1y', 'never'
  },
});
const { token } = response.body.data;
// ⚠️ Lưu lại ngay — token chỉ hiển thị 1 lần

Lấy danh sách keys

const response = await agent.resource('apiKeys').list({
  sort: ['-createdAt'],
});
// response.body.data = [{ id, name, roleName, expiresIn, createdAt, ... }]
// Lưu ý: field `token` bị ẩn trong response list

Xoá API Key (vô hiệu hoá token)

await agent.resource('apiKeys').destroy({
  filterByTargetKey: keyId,
});
// Token JWT bị xoá khỏi DB → request dùng token này sẽ bị từ chối

Sử dụng key từ hệ thống bên ngoài

Với Authorization header (khuyến nghị)

curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://your-domain/api/posts:list

Ví dụ: tạo bản ghi mới

curl -X POST \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"values": {"title": "Bài viết mới", "status": "draft"}}' \
  https://your-domain/api/posts:create

Database Collection — apiKeys

Field	Kiểu	Mô tả
id	bigint	ID tự tăng
name	string	Tên mô tả key (ví dụ: "CI/CD Pipeline")
roleName	string	Role gán cho key — quyết định quyền truy cập
expiresIn	string	Thời hạn token: 30d, 90d, 1y, never
token	string	JWT — chỉ hiển thị 1 lần khi tạo, sau đó bị ẩn
userId	bigint	ID của user đã tạo key
sort	integer	Thứ tự sắp xếp
createdAt	timestamp	Thời gian tạo key

Phân quyền (ACL)

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

Ngoài ra, middleware scope đảm bảo:

• apiKeys:list — chỉ trả về keys có userId = user hiện tại
• apiKeys:destroy — chỉ cho phép xoá keys có userId = user hiện tại

Giới hạn kỹ thuật

Tham số	Giá trị	Ghi chú
Số key tối đa / user	20	Cấu hình được
Token format	JWT (HS256)	Ký bởi @digiforce-nc/auth
Key hết hạn	Tự động bị từ chối	Response 401 Unauthorized
Rate limit	Như user bình thường	Áp dụng theo role