Última atualização
Autenticação
Toda requisição leva uma chave de API do espaço de trabalho como token Bearer. As chaves têm escopos, podem ser revogadas e ficam vinculadas à carteira de créditos de um único espaço de trabalho.
Chaves Bearer
Envie a chave no cabeçalho Authorization como Bearer <key>. As chaves têm o formato ttk_live_<id>_<secret>; o painel as lista pelo prefixo ttk_live_<id>. Crie-as em Settings → API keys; a chave completa é exibida uma única vez. Uma chave age em nome do proprietário do espaço de trabalho, limitada aos seus escopos.
curl "https://api.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Escopos
Uma chave só pode chamar os endpoints cobertos pelos seus escopos. Escolha o menor conjunto que resolva o trabalho; você sempre pode criar uma segunda chave. Requisições fora dos escopos da chave, e rotas exclusivas do painel (lista de monitoramento, salas, espaço de trabalho, cobrança), retornam 403 com o código insufficient_scope; um plano sem o módulo retorna module_not_entitled.
| Escopo | Concede |
|---|---|
live:read | Sessões de LIVE, uma sessão, desempenho do criador e atualização ao vivo. Exige o módulo LIVE. |
rank:read | Rankings oficiais, regiões e histórico de rankings. Exige o módulo LIVE. |
shop:read | Também é necessário para rankings de shopping (board começando com shopping). |
creator:read | Busca de criadores, perfis, análise, alterações, seguidos, seguidores e insights. Exige o módulo Consulta. |
content:read | Vídeos, comentários de vídeos e os vídeos de um criador. Exige o módulo Consulta. |
trend:read | Tendências regionais. Exige o módulo Consulta. |
export | Criar, listar e baixar exportações. |
webhook:manage | Regras de alerta em todos os canais e testes de regras. Exige o módulo LIVE. |
keys:manage | Listar, criar e revogar chaves de API; ler direitos do plano e uso. |
live:stream · gifter:read | Reservados para endpoints futuros; ainda não concedem nada. |
Rotação de chaves
Primeiro crie a chave substituta, coloque-a em produção e depois revogue a antiga na mesma tela. A revogação é imediata: as requisições em andamento terminam e as novas falham com 401.
As chaves também podem ser criadas com uma data expiresAt; depois dela, respondem 401.
Erros
| Status | Código | Significado |
|---|---|---|
| 401 | unauthorized | Chave ausente, malformada, revogada ou expirada, ou espaço de trabalho inativo. |
| 403 | insufficient_scope | A chave é válida, mas não tem o escopo, ou a rota é exclusiva do painel. |
| 403 | module_not_entitled | O plano do espaço de trabalho não inclui o módulo LIVE ou Consulta. |
| 402 | credit_cap_exceeded | Os créditos do mês acabaram. Veja Créditos e Erros. |