Developer Docs
Authentication
Bearer API keys, scopes, and the data-plane / control-plane boundary.
The API authenticates with a workspace API key presented as a bearer token. Keys are scoped: a key may only reach the datasets its scopes grant.
The Authorization header
Authorization: Bearer ttk_live_…Create, list and revoke keys in Settings › Developer keys. The secret is shown once at creation; rotate a key by creating a new one and revoking the old. Never embed a key in a browser or a public repo — it carries your credits.
Scopes
A key is granted a set of scopes; a call to a route the key is not scoped for is rejected 403. Scopes map to datasets across the two product modules.
| Scope | Module | Grants access to |
|---|---|---|
rank:read | Live | Rankings boards (official + derived) |
live:read | Live | Persisted LIVE sessions & per-creator performance |
live:stream | Live | Realtime WebSocket LIVE events (any creator) |
gifter:read | Live | Gifter / whale intelligence |
creator:read | Lookup Data | Creator profile, change history, analysis, follow lists |
content:read | Lookup Data | A creator's videos, one video, its comments |
trend:read | Lookup Data | Trending hashtags & sounds |
export | Both | Asynchronous bulk dataset exports |
webhook:manage | Account | Create/read/update/delete alert (webhook) rules |
keys:manage | Account | List & revoke API keys; read usage & entitlements |
Data-plane vs control-plane
API keys reach the data plane only. Control-plane routes — creating a key, changing account settings — are session-only and reject an API-key actor with 403 insufficient_scope, even one carrying keys:manage.
The two management scopes are still real write power, not read-only:keys:manage can list and revoke keys (and read usage/entitlements), and webhook:manage can create, update and delete alert (webhook) rules. Treat a leaked key accordingly — scope keys to the minimum they need.