Última actualización
Autenticación
Cada solicitud lleva una clave de API del espacio de trabajo como token Bearer. Las claves tienen alcances, se pueden revocar y están vinculadas a la billetera de créditos de un espacio de trabajo.
Claves Bearer
Envía la clave en el encabezado Authorization como Bearer <key>. Las claves tienen la forma ttk_live_<id>_<secret>; el panel las muestra por el prefijo ttk_live_<id>. Créalas en Configuración → Claves de API; la clave completa se muestra una sola vez. Una clave actúa en nombre del propietario del espacio de trabajo, limitada a sus alcances.
curl "https://api.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Alcances
Una clave solo puede llamar a los endpoints que cubren sus alcances. Elige el conjunto más pequeño que resuelva la tarea; siempre puedes crear una segunda clave. Las solicitudes fuera de los alcances de la clave, y las rutas exclusivas del panel (lista de seguimiento, salas, espacio de trabajo, facturación), devuelven 403 con el código insufficient_scope; un plan sin el módulo devuelve module_not_entitled.
| Alcance | Otorga |
|---|---|
live:read | Sesiones LIVE, una sesión, rendimiento del creador y actualización en vivo. Requiere el módulo LIVE. |
rank:read | Rankings oficiales, regiones e historial de rankings. Requiere el módulo LIVE. |
shop:read | También es necesario para los rankings de shopping (board que empieza por shopping). |
creator:read | Búsqueda de creadores, perfiles, análisis, cambios, seguidos, seguidores e insights. Requiere el módulo Búsqueda. |
content:read | Videos, comentarios de videos y los videos de un creador. Requiere el módulo Búsqueda. |
trend:read | Tendencias regionales. Requiere el módulo Búsqueda. |
export | Crear, listar y descargar exportaciones. |
webhook:manage | Reglas de alerta en todos los canales y pruebas de reglas. Requiere el módulo LIVE. |
keys:manage | Listar, crear y revocar claves de API; leer el plan contratado y el uso. |
live:stream · gifter:read | Reservados para próximos endpoints; por ahora no otorgan nada. |
Rotación de claves
Primero crea la clave de reemplazo, despliégala y luego revoca la anterior desde la misma pantalla. La revocación es inmediata: las solicitudes en curso terminan y las nuevas fallan con 401.
También puedes crear claves con una fecha expiresAt; después de esa fecha responden 401.
Errores
| Estado | Código | Significado |
|---|---|---|
| 401 | unauthorized | Clave ausente, mal formada, revocada o vencida, o un espacio de trabajo inactivo. |
| 403 | insufficient_scope | La clave es válida pero no tiene el alcance, o la ruta es exclusiva del panel. |
| 403 | module_not_entitled | El plan del espacio de trabajo no incluye el módulo LIVE o Búsqueda. |
| 402 | credit_cap_exceeded | Se agotaron los créditos del mes. Consulta Créditos y Errores. |