RoomScope

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"
Một ví duy nhất
Key tiêu credit của workspace sở hữu nó. Mức sử dụng từ API và từ dashboard hiển thị chung tại Cài đặt → Mức sử dụng.

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.

ScopeCho phép
live:readPhiê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:readBảng xếp hạng chính thức, khu vực và lịch sử bảng. Cần module LIVE.
shop:readCần thêm cho các bảng shopping (board bắt đầu bằng shopping).
creator:readTìm kiếm creator, hồ sơ, phân tích, thay đổi, đang follow, follower và insight. Cần module Tra cứu.
content:readVideo, bình luận video và video của một creator. Cần module Tra cứu.
trend:readXu hướng theo khu vực. Cần module Tra cứu.
exportTạo, liệt kê và tải xuống các bản xuất.
webhook:manageLuật cảnh báo trên mọi kênh và thử luật. Cần module LIVE.
keys:manageLiệ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:readDà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áiCodeÝ nghĩa
401unauthorizedKey bị thiếu, sai định dạng, đã thu hồi hoặc hết hạn, hoặc workspace không hoạt động.
403insufficient_scopeKey hợp lệ nhưng thiếu scope, hoặc route chỉ dành cho dashboard.
403module_not_entitledGói của workspace không bao gồm module LIVE hoặc Tra cứu.
402credit_cap_exceededCredit của tháng đã dùng hết. Xem Credit và Lỗi.
Trang này có hữu ích không?