最後更新
身分驗證
每個請求都以 Bearer 權杖的形式攜帶工作區的 API 金鑰。金鑰具有權限範圍、可撤銷，並綁定單一工作區的點數錢包。
Bearer 金鑰
請在 Authorization 標頭中以 Bearer <key> 的格式傳送金鑰。金鑰的格式為 ttk_live_<id>_<secret>；主控台會以 ttk_live_<id> 前綴列出金鑰。請在 設定 → API 金鑰中建立金鑰，完整金鑰只會顯示一次。金鑰代表工作區擁有者執行操作，但僅限於其權限範圍。
curl "https://api.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"同一個錢包
金鑰會消耗其所屬工作區的點數。來自 API 與主控台的用量會一併顯示在 設定 → 用量 中。
權限範圍
金鑰只能呼叫其權限範圍涵蓋的端點。請選擇足以完成工作的最小範圍；需要時隨時可以再建立第二把金鑰。超出金鑰權限範圍的請求，以及僅限主控台的路由（觀察清單、直播間、工作區、帳務），會回傳 403 與錯誤碼 insufficient_scope；方案未包含對應模組時則回傳 module_not_entitled。
| 權限範圍 | 授予內容 |
|---|---|
live:read | LIVE 場次清單、單一場次、創作者表現與即時重新整理。需要 LIVE 模組。 |
rank:read | 官方排行榜、地區與榜單歷史紀錄。需要 LIVE 模組。 |
shop:read | 購物榜（board 以 shopping 開頭）另外需要此權限範圍。 |
creator:read | 創作者搜尋、檔案、分析、變化、追蹤中、粉絲與洞察。需要查詢模組。 |
content:read | 影片、影片留言與創作者的影片。需要查詢模組。 |
trend:read | 地區趨勢。需要查詢模組。 |
export | 建立、列出與下載匯出檔。 |
webhook:manage | 所有通道的提醒規則，以及規則測試。需要 LIVE 模組。 |
keys:manage | 列出、建立與撤銷 API 金鑰；讀取方案權益與用量。 |
live:stream · gifter:read | 保留給即將推出的端點，目前不授予任何權限。 |
金鑰輪替
請先建立替換用的新金鑰並完成部署，再從同一個畫面撤銷舊金鑰。撤銷會立即生效：進行中的請求會正常完成，新的請求則會以 401 失敗。
建立金鑰時也可以設定 expiresAt 到期日，到期後的請求會回傳 401。
錯誤
| 狀態 | 錯誤碼 | 意義 |
|---|---|---|
| 401 | unauthorized | 金鑰缺少、格式錯誤、已撤銷或已過期，或工作區已停用。 |
| 403 | insufficient_scope | 金鑰有效但缺少該權限範圍，或該路由僅限主控台使用。 |
| 403 | module_not_entitled | 工作區的方案未包含 LIVE 或查詢模組。 |
| 402 | credit_cap_exceeded | 本月點數已用完。請參閱點數與錯誤。 |
這個頁面對你有幫助嗎？