Cập nhật lần cuối
Xác thực
Mỗi request mang một API key của workspace dưới dạng Bearer token. Key có scope, có thể thu hồi và gắn với ví credit của một workspace.
Bearer key
Gửi key trong header Authorization dưới dạng Bearer <key>. Key có dạng ttk_live_<id>_<secret>; dashboard liệt kê chúng theo tiền tố ttk_live_<id>. Tạo key tại Cài đặt → API key; key đầy đủ chỉ hiện một lần. Một key hành động thay cho chủ workspace, trong giới hạn các scope của nó.
curl "https://api.next.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Scope
Một key chỉ gọi được các endpoint nằm trong scope của nó. Hãy chọn tập scope nhỏ nhất đủ cho công việc; bạn luôn có thể tạo thêm key thứ hai. Request ngoài scope của key, và các route chỉ dành cho dashboard (watchlist, phòng, workspace, thanh toán), trả về 403 với code insufficient_scope; gói không có module tương ứng trả về module_not_entitled.
| Scope | Cho phép |
|---|---|
live:read | Phiên LIVE, một phiên, hiệu suất creator và làm mới trạng thái live. Cần module LIVE. |
rank:read | Bảng xếp hạng chính thức, khu vực và lịch sử bảng. Cần module LIVE. |
shop:read | Cần thêm cho các bảng shopping (board bắt đầu bằng shopping). |
creator:read | Tìm kiếm creator, hồ sơ, phân tích, thay đổi, đang follow, follower và insight. Cần module Tra cứu. |
content:read | Video, bình luận video và video của một creator. Cần module Tra cứu. |
trend:read | Xu hướng theo khu vực. Cần module Tra cứu. |
export | Tạo, liệt kê và tải xuống các bản xuất. |
webhook:manage | Luật cảnh báo trên mọi kênh và thử luật. Cần module LIVE. |
keys:manage | Liệt kê, tạo và thu hồi API key; đọc quyền lợi gói và mức sử dụng. |
live:stream · gifter:read | Dành cho các endpoint sắp ra mắt; hiện chưa cấp quyền gì. |
Xoay vòng key
Tạo key thay thế trước, triển khai nó, rồi thu hồi key cũ ngay trên cùng màn hình. Việc thu hồi có hiệu lực tức thì: các request đang chạy vẫn hoàn tất, request mới sẽ thất bại với 401.
Key cũng có thể được tạo kèm ngày expiresAt; sau ngày đó key sẽ trả về 401.
Lỗi
| Trạng thái | Code | Ý nghĩa |
|---|---|---|
| 401 | unauthorized | Key bị thiếu, sai định dạng, đã thu hồi hoặc hết hạn, hoặc workspace không hoạt động. |
| 403 | insufficient_scope | Key hợp lệ nhưng thiếu scope, hoặc route chỉ dành cho dashboard. |
| 403 | module_not_entitled | Gói của workspace không bao gồm module LIVE hoặc Tra cứu. |
| 402 | credit_cap_exceeded | Credit của tháng đã dùng hết. Xem Credit và Lỗi. |