Xác Thực API Key

Tất cả các endpoint của ImageCoreAPI (ngoại trừ /v1/health) đều yêu cầu xác thực bằng API Key hợp lệ được cấp phát bởi quản trị viên.

---

1. Phương Thức Truyền API Key

Hệ thống hỗ trợ 2 chuẩn truyền khóa thông qua HTTP Header:

Cách 1: Header X-API-Key (Khuyên dùng)

GET /v1/me HTTP/1.1
Host: api.yourdomain.com
X-API-Key: mkuph_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Cách 2: Header Authorization: Bearer

GET /v1/me HTTP/1.1
Host: api.yourdomain.com
Authorization: Bearer mkuph_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

---

2. Định Dạng Key Hợp Lệ

Khóa truy cập do ImageCoreAPI cung cấp luôn bắt đầu bằng tiền tố mkuph_:

• Ví dụ mẫu: mkuph_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

---

3. Các Lỗi Xác Thực Thường Gặp

Khi gửi request, nếu thông tin xác thực không hợp lệ, hệ thống sẽ phản hồi HTTP status code tương ứng:

Mã HTTP	Mã lỗi (code)	Nguyên nhân cụ thể	Giải pháp khắc phục
401	INVALID_KEY	Thiếu Header xác thực, sai định dạng key, key không tồn tại, hoặc key đã hết hạn / bị vô hiệu hóa	Kiểm tra xem đã truyền đúng header X-API-Key chưa, xóa khoảng trắng thừa ở hai đầu key, hoặc liên hệ admin để cấp lại
403	PLATFORM_NOT_ALLOWED	Key chưa được cấp quyền truy cập sàn này (ví dụ: key chỉ có quyền tiktok nhưng lại gọi API Shopee)	Liên hệ Quản trị viên để mở quyền sàn tương ứng trên API Key của bạn
429	AUTH_THROTTLED	Địa chỉ IP của bạn gửi quá 20 request sai key liên tiếp trong vòng 60 giây	Tạm dừng gửi request trong 60 giây để hệ thống tự động mở khóa IP

---

4. Nguyên Tắc Bảo Mật Cho Nhà Phát Triển

Để đảm bảo an toàn cho hạn mức và tài khoản của bạn, vui lòng tuân thủ các nguyên tắc sau:

1. Không nhúng Key vào Frontend / Client-side:

   • Tuyệt đối không hardcode API Key trong ứng dụng Mobile (React Native, Flutter) hoặc mã nguồn Web (React, Vue, HTML/JS) chạy trực tiếp trên trình duyệt của người dùng.
   • Luôn gọi API thông qua Server / Backend của bạn để giấu API Key.

2. Sử dụng Biến Môi Trường (.env):

   • Lưu trữ key trong file .env trên máy chủ và thêm file này vào .gitignore để tránh vô tình đẩy mã nguồn lên GitHub/GitLab.

3. Thu hồi và Cấp lại khi bị lộ:

   • Nếu bạn phát hiện key bị lộ hoặc nghi ngờ có bên thứ ba sử dụng trái phép hạn mức của bạn, hãy liên hệ ngay với Quản trị viên để vô hiệu hóa key cũ và cấp mới trong vài giây.