Cấp khoá API cho ứng dụng bên thứ ba, AI agent (Claude, ChatGPT, Gemini, Codex, MCP client) và webhook — theo đúng phạm vi quyền bạn cho phép.
📌 Vị trí: Thiết lập → Kết nối → AI Agent & API
1. Danh sách khoá API
Ba tab AI Agent & API Key / Ứng dụng kết nối / Webhooks (mũi tên trên), liên kết Mở wizard Tích hợp AI (mũi tên giữa) và nút
| + Tạo khoá (mũi tên dưới) |
|---|
| Thành phần | Nội dung | Dùng khi nào |
|---|---|---|
| Tab AI Agent & API Key | Quản lý tất cả khoá API của workspace. Bảng gồm: TÊN · NGUỒN · KHOÁ · PHẠM VI QUYỀN · TRẠNG THÁI · HẾT HẠN · NGÀY TẠO. | Cấp và thu hồi khoá |
| Tab Ứng dụng kết nối | Các ứng dụng bên thứ ba đang dùng khoá. | Kiểm tra ứng dụng nào đang truy cập dữ liệu |
| Tab Webhooks | Khai báo URL nhận sự kiện từ NextX. | Đồng bộ tự động sang hệ thống khác |
| Mở wizard Tích hợp AI → | Nhấn liên kết → wizard tự chọn sẵn đúng bộ quyền cho Claude / ChatGPT / Gemini / Codex / MCP client. | Cách nhanh nhất để nối một AI agent |
| Bộ lọc Đang dùng / Đã thu hồi / Tất cả | Lọc khoá theo trạng thái, kèm số lượng trong ngoặc. | Soát lại khoá cũ đã thu hồi |
| + Tạo khoá | Nhấn → mở hộp thoại tạo khoá API mới. | Cấp quyền cho một hệ thống mới |
2. Tạo khoá API
Khoá dùng để “hệ thống của bạn gọi API NextX qua header X-Api-Key”.
Chọn thời hạn khoá (mũi tên trên), chọn phạm vi quyền (mũi tên giữa) và nút Tạo khoá (mũi tên dưới)
| Trường | Cách hoạt động | Gợi ý |
|---|---|---|
| Tên khoá * | Theo quy ước: Hệ thống cầm khoá — mục đích. | ERP Bravor — đồng bộ đơn hàng |
| Hết hạn | Bốn lựa chọn: Không hết hạn · 90 ngày · 1 năm · Chọn ngày… | Chọn 90 ngày cho tích hợp thử nghiệm; tránh Không hết hạn |
| Mô tả | Ghi rõ khoá dùng làm gì, ai chịu trách nhiệm. | Người tiếp nhận sau sẽ hiểu ngay |
| Gợi ý sẵn | Bốn nhãn bấm nhanh: Claude MCP — chỉ đọc · ERP — đồng bộ đơn hàng · Web form — đẩy lead · n8n — tự động hoá. | Bấm nhãn gần nhất rồi chỉnh lại |
2.1 Ba mức phạm vi quyền
| Phạm vi quyền * | Khoá làm được gì | Phù hợp khi nào |
|---|---|---|
| Chỉ đọc | Mọi quyền xem (157 mã *.view) của các phân hệ workspace đang bật. | Mặc định nên chọn — cho AI agent, báo cáo, dashboard ngoài |
| Tuỳ chọn theo phân hệ | Tick từng mã quyền — danh sách lấy từ hệ thống phân quyền, không thể gõ sai. | Tích hợp chỉ cần một nghiệp vụ (ví dụ chỉ tạo đơn hàng) |
| Toàn quyền workspace | Khoá làm được mọi thứ tài khoản Owner làm được qua API. | Hạn chế tối đa — chỉ dùng cho hệ thống nội bộ đã kiểm soát chặt |
⚠️ Rủi ro bảo mật cần cân nhắc: Khoá Toàn quyền workspace tương đương trao tài khoản chủ doanh nghiệp cho một hệ thống khác — nếu khoá bị lộ, người có khoá làm được mọi thao tác qua API. Hãy chọn Chỉ đọc hoặc Tuỳ chọn theo phân hệ trước, chỉ nâng quyền khi thực sự cần.
⚠️ Có bước xác thực bổ sung: Màn hình ghi rõ “Bấm Tạo khoá sẽ hỏi mã xác thực gửi …” — bạn cần nhập mã xác thực để hoàn tất. Khoá dùng mã quyền chính xác (không hỗ trợ wildcard), picker chỉ cho tick mã có thật.
💡 Kinh nghiệm quản lý khoá: Đặt hạn 90 ngày và ghi tên theo quy ước — mỗi kỳ gia hạn là một lần rà soát xem tích hợp đó còn dùng không. Khoá không còn dùng thì thu hồi ngay thay vì để tồn tại vô thời hạn.