Cập nhật lần cuối
Authentication
Every request carries a workspace API key as a Bearer token. Keys are scoped, revocable and tied to one workspace’s credit wallet.
Bearer keys
Send the key in the Authorization header as Bearer <key>. Keys look like ttk_live_<id>_<secret>; the dashboard lists them by the ttk_live_<id> prefix. Create them under Settings → API keys; the full key is shown once. A key acts for the workspace owner, limited to its scopes.
curl "https://api.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Scopes
A key can only call endpoints covered by its scopes. Pick the smallest set that does the job; you can always create a second key. Requests outside the key’s scopes, and dashboard-only routes (watchlist, rooms, workspace, billing), return 403 with code insufficient_scope; a plan without the module returns module_not_entitled.
| Scope | Grants |
|---|---|
live:read | LIVE sessions, a session, creator performance and live refresh. Needs the Live module. |
rank:read | Official leaderboards, regions and board history. Needs the Live module. |
shop:read | Also required for shopping boards (board starting with shopping). |
creator:read | Creator search, profiles, analysis, changes, following, followers and insights. Needs the Lookup module. |
content:read | Videos, video comments and a creator’s videos. Needs the Lookup module. |
trend:read | Regional trends. Needs the Lookup module. |
export | Create, list and download exports. |
webhook:manage | Alert rules on every channel, and rule tests. Needs the Live module. |
keys:manage | List, create and revoke API keys; read entitlements and usage. |
live:stream · gifter:read | Reserved for upcoming endpoints; they grant nothing yet. |
Key rotation
Create the replacement key first, deploy it, then revoke the old one from the same screen. Revocation is immediate: in-flight requests finish, new ones fail with 401.
Keys can also be created with an expiresAt date, after which they answer 401.
Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing, malformed, revoked or expired key, or an inactive workspace. |
| 403 | insufficient_scope | The key is valid but lacks the scope, or the route is dashboard-only. |
| 403 | module_not_entitled | The workspace’s plan does not include the Live or Lookup module. |
| 402 | credit_cap_exceeded | The month’s credits are spent. See Credits and Errors. |