Xác thực & API Key
Mọi yêu cầu tới AIGate đều cần API key. Trang này hướng dẫn tạo, quản lý, và bảo mật key đúng cách.
Cách xác thực
Gửi API key trong header Authorization theo chuẩn Bearer Token:
Authorization: Bearer aig_xxxxxxxxxxxxxxxxxxxxxxxxHoặc với header tùy chỉnh (tương đương):
X-API-Key: aig_xxxxxxxxxxxxxxxxxxxxxxxxĐăng nhập tài khoản
Tất cả tài khoản AIGate đều dùng SSO chung của hệ sinh thái Truyền Nghề:
- Auth Hub: auth.truyennghe.edu.vn
- Hỗ trợ đăng nhập: Email/Mật khẩu, Google, Facebook, Zalo
- Một tài khoản — nhiều dịch vụ: AIGate, Truyền Nghề LMS, Chuyên Gia Phong Thủy…
Đăng nhập xong, bạn sẽ được chuyển về cp.aigate.id.vn để quản lý keys, credits, và lịch sử yêu cầu.
Tạo API Key
- Đăng nhập vào cp.aigate.id.vn
- Vào menu API Keys
- Nhấn Tạo key mới
- Đặt tên (ví dụ: Production — Web App) và chọn quyền hạn
- Sao chép key — chỉ hiển thị một lần duy nhất
Phân quyền theo Key
Mỗi key có thể được giới hạn theo:
| Loại giới hạn | Mô tả | Ví dụ |
|---|---|---|
| Endpoint | Chỉ cho phép gọi endpoint cụ thể | Chỉ /v1/generate/image |
| IP whitelist | Chặn yêu cầu ngoài IP cho phép | 113.161.0.0/16 |
| Rate limit | Số yêu cầu tối đa / phút | 60 req/phút |
| Credits cap | Giới hạn credits có thể tiêu | 500 credits/ngày |
| Domain (Origin) | Chỉ cho phép từ domain | example.com |
Đặt giới hạn cho từng key giúp giảm rủi ro nếu key bị lộ — kẻ tấn công không thể tiêu hết credits của bạn.
Bảo mật API Key
Nên làm ✓
- Lưu key trong biến môi trường (
.env) hoặc trình quản lý secret (AWS Secrets Manager, Vault) - Tạo key riêng cho từng môi trường (dev, staging, prod) — dễ thu hồi khi cần
- Bật IP whitelist cho key production
- Đặt credits cap để giới hạn thiệt hại
- Xoay key định kỳ (3-6 tháng)
- Dùng scoped key — mỗi service chỉ có quyền cần thiết
Không nên ❌
- Nhúng API key trực tiếp vào client-side JavaScript / mobile app — luôn proxy qua server
- Commit key vào git (nếu lỡ commit, thu hồi ngay)
- Chia sẻ key qua chat/email không mã hóa
- Dùng cùng một key cho nhiều dự án
Thu hồi (Revoke) Key
Khi key bị lộ hoặc không còn dùng:
- Vào cp.aigate.id.vn → API Keys
- Tìm key cần thu hồi → nhấn Revoke
- Hiệu lực ngay lập tức — mọi yêu cầu sau đó sẽ trả 401
💡 Mẹo: Thu hồi key không hoàn lại credits đã tiêu. Nếu nghi ngờ bị tấn công, kiểm tra Logs để xem các yêu cầu khả nghi.
OAuth 2.0 cho ứng dụng end-user
Nếu bạn xây ứng dụng cho người dùng cuối (không phải tự dùng), nên dùng OAuth 2.0 thay vì API key:
- Người dùng đăng nhập qua
auth.truyennghe.edu.vn - App nhận access token có giới hạn quyền
- Token tự động hết hạn (1h), refresh khi cần
Đăng ký OAuth client tại cp.aigate.id.vn → Developer → OAuth Clients. Tham khảo Webhooks để nhận callback xác thực.
Mã lỗi xác thực
| HTTP | Mã | Nguyên nhân | Cách xử lý |
|---|---|---|---|
| 401 | missing_key | Không có header Authorization | Thêm Bearer aig_xxx |
| 401 | invalid_key | Key không tồn tại / sai định dạng | Kiểm tra lại key |
| 401 | revoked_key | Key đã bị thu hồi | Tạo key mới |
| 403 | scope_denied | Key không có quyền cho endpoint này | Tạo key mới với scope phù hợp |
| 403 | ip_blocked | IP không nằm trong whitelist | Sửa whitelist hoặc tắt |
Tiếp theo
👉 Sinh ảnh AI — tham chiếu đầy đủ tham số & models
👉 Webhooks — nhận thông báo khi job hoàn thành