API key và bảo mật
Tạo, giới hạn và quản lý Developer API key an toàn.
Tạo API key
- Mở Admin Panel và chọn trợ lý.
- Vào API cho nhà phát triển.
- Chọn Tạo khóa API, đặt tên và chọn scopes cần dùng.
- Sao chép key
ac_…vào secret manager phía máy chủ.
Full key chỉ hiển thị một lần. Mỗi key thuộc một trợ lý và request không cần truyền assistant_id. Key kết thúc bằng checksum nên key gõ sai hoặc bị cắt sẽ bị từ chối ngay với INVALID_API_KEY, và công cụ secret scanning có thể nhận diện key bị lộ.
Scopes
| Scope | Cho phép |
|---|---|
chat:write | Tạo chat response dạng JSON hoặc SSE. |
files:write | Upload tệp cho external user. |
conversations:read | Đọc hội thoại và danh sách tin nhắn. |
feedback:write | Gửi feedback cho tin nhắn. |
voice:connect | Tạo voice session và kết nối WebSocket. |
users:delete | Xóa vĩnh viễn dữ liệu của end user. |
Chỉ cấp scopes cần thiết. Dùng key riêng cho từng ứng dụng và môi trường; thêm IP allowlist nếu backend có outbound IP cố định. Rate limit dùng chung cho mọi key của một trợ lý.
Billing và dữ liệu người dùng
- Chat và voice sử dụng credits của billing owner của trợ lý.
- Model và tính năng được giới hạn theo plan của owner.
- Hội thoại, tệp và memory được tách theo trợ lý và
external_user_id. - Giữ
external_user_idổn định và không dùng email, số điện thoại hoặc secret.
Preview chưa có sandbox riêng. Request staging vẫn có thể tạo dữ liệu thật và trừ credits. Nên dùng assistant và API key staging riêng.
Bảo vệ API key
- Chỉ gửi key qua HTTPS bằng
Authorization: Bearer .... - Không đặt key trong browser, ứng dụng mobile, URL, source control hoặc log.
- Backend phải xác thực end user trước khi ánh xạ sang
external_user_id. - Với browser voice, backend tạo session rồi chỉ trả
token,expires_atvàwebsocket_urlcho client. - Với mobile/desktop app, dùng backend trung gian hoặc OAuth Authorization Code + PKCE để cấp token theo user/installation. Keychain/Keystore chỉ dùng lưu token hay private key riêng của installation, không làm Developer API key nhúng chung trở nên bí mật.
Sửa, thay hoặc thu hồi key
Edit đổi tên hoặc IP allowlist của key ngay tại chỗ; secret vẫn tiếp tục hoạt động. Xóa trống allowlist nghĩa là cho phép mọi IP. Scopes và thời hạn không sửa được: hãy tạo key mới để thay đổi.
Rotate tạo key thay thế với cùng tên, scopes, IP allowlist và thời hạn, rồi ngừng key cũ vào thời điểm bạn chọn:
| Lựa chọn | Khi nào dùng |
|---|---|
| Ngay lập tức | Key có thể đã bị lộ. Request dùng key cũ lỗi ngay. |
| Sau 1 giờ, 24 giờ hoặc 7 ngày | Rotate theo kế hoạch. Key cũ vẫn hoạt động đến hạn, sau đó trả API_KEY_EXPIRED. |
Khi rotate theo kế hoạch, deploy key mới cho mọi instance và gửi request thử trước khi hết thời gian ân hạn.
Revoke chặn key ngay và không thể hoàn tác. Delete xóa key khỏi danh sách và key ngừng hoạt động ngay. Việc tạo, sửa, rotate, revoke và xóa key được ghi vào audit log kèm admin thực hiện.