Xác thực
Mọi request xác thực bằng API key trong header Authorization chuẩn. Key tạo trong dashboard, gán scope và giới hạn theo từng mục đích dùng.
Header Authorization
mọi request
Authorization: Bearer sk-gw-...
Đây là cơ chế xác thực duy nhất — không token trên query string, không cookie. SDK OpenAI tự gửi header này khi bạn đặt api_key.
Định dạng và cách lưu key
- Key bắt đầu bằng
sk-gw-. Key đầy đủ chỉ hiện đúng một lần lúc tạo. Hệ thống chỉ lưu hash SHA-256 và 4 ký tự cuối — key mất là không lấy lại được, chỉ tạo key mới. - Tạo, thu hồi và cấu hình key ở trang API keys trong dashboard. API quản lý key bằng code nằm trong kế hoạch, chưa mở.
Scope
Một key mang một hoặc cả hai scope; endpoint ngoài scope trả 403.
| Scope | Cho phép |
|---|---|
chat | Inference: POST /v1/chat/completions |
usage:read | Bề mặt billing chỉ-đọc: GET /v1/credits, GET /v1/generation, GET /v1/usage |
GET /v1/models chỉ cần key hợp lệ, không đòi scope riêng. Thiếu scope trả missing_scope; message nêu rõ scope endpoint cần.
Giới hạn per-key
Mỗi giới hạn là tùy chọn, đặt theo từng key trong dashboard:
- Allowed models — gọi model ngoài danh sách trả
403 model_not_allowed. - IP allowlist — gọi từ IP khác trả
401 ip_not_allowed(bản thân key vẫn hợp lệ). - Ngày hết hạn — quá hạn, key trả
401 key_expired. - Trần tốc độ và chi tiêu — rpm/tpm per-key và ngân sách ngày có thể đặt thấp hơn giới hạn của tổ chức; xem Rate limits.
Bốn mã 401
| Mã | Ý nghĩa |
|---|---|
invalid_api_key | Key không tồn tại. Kiểm tra đã chép trọn vẹn chưa, kể cả tiền tố sk-gw-. |
key_revoked | Key đã bị thu hồi trong dashboard. Tạo key mới. |
key_expired | Key đã quá hạn. Tạo key mới. |
ip_not_allowed | Key đúng nhưng IP gọi nằm ngoài allowlist của key. |
Giữ key an toàn
- Nạp key từ biến môi trường hoặc secret manager — không bao giờ commit.
- Gọi gateway từ backend. Key nhúng trong trình duyệt hay app mobile là key công khai.
- Mỗi ứng dụng/môi trường một key riêng để lộ một key thì thiệt hại nhỏ.
- Đặt giới hạn per-key (rpm, tpm, ngân sách ngày) ngay lúc tạo key — đó là trần thiệt hại trả trước nếu key lộ.
Nếu key bị lộ
- Thu hồi ngay ở trang API keys — hiệu lực tức thì, request đang bay chạy nốt nhưng request mới không xác thực được nữa.
- Tạo key thay thế và xoay vào deployment của bạn.
- Soi
GET /v1/usagevà log request tìm traffic lạ trong cửa sổ bị lộ — mức tiêu bị chặn bởi số dư và ngân sách ngày per-key (nếu đặt), trả trước nghĩa là ca xấu nhất có trần. - Thấy gì bất thường hoặc cần trợ giúp đọc cửa sổ đó, viết về [email protected] kèm 4 ký tự cuối của key (đừng bao giờ gửi key đầy đủ).