API de TikTok para negocios: tokens de acceso de 24 horas, renovación y revocación
Un token de acceso de la API de TikTok para negocios dura 24 horas y se envía en el encabezado Access-Token. Una app lo obtiene canjeando el código de autorización del titular en /tt_user/oauth2/token/, junto con un token de actualización que dura un año y renueva el acceso en /tt_user/oauth2/refresh_token/. Se revoca en /tt_user/oauth2/revoke/, y sus permisos otorgados se consultan en /tt_user/token_info/get/.
easyCoexistence canjea el código cuando una cuenta de TikTok inicia sesión, renueva el token de 24 horas antes de que venza y revisa la cuenta cada 6 horas aproximadamente, para que Claude, ChatGPT o tu propio código llamen a TikTok con un token vigente, que get_social_credentials entrega a tus scripts.
Duración de un token de acceso de cuenta de TikTok; cada respuesta indica los segundos restantes en expires_in.
Validez del token de actualización emitido con él; refresh_token_expires_in indica sus segundos restantes.
Tiempo que el código de autorización de la redirección sigue siendo válido; solo puede canjearse una vez.
El ID específico de la aplicación de la cuenta, devuelto con cada token y enviado como business_id en llamadas a la Accounts API.
El token_type que devuelve TikTok: quien tenga el token puede usarlo para acceder a los recursos de la cuenta.
El ID de cuenta que /tt_user/token_info/get/ devuelve junto con el scope del token, utilizable como business_id en llamadas a la Accounts API.
¿Cómo llega el código de autorización a tu app?
A través de la URL de autorización del titular de la cuenta de TikTok, que TikTok genera para una app de desarrollador en Mis apps, Detalle de la app, Información básica, una vez que la app tiene el permiso TikTok Accounts. El titular de la cuenta la abre, revisa los permisos y los aprueba. Después TikTok envía el navegador a la URL de redirección de la app con un auth_code añadido, más cualquier valor state que llevara la URL de autorización, y ese código es válido durante 10 minutos y para un único canje.
- URL de redirección: absoluta, que empieza por https://, termina en /, sin cadena de consulta, ancla ni puerto, y mide entre 10 y 512 caracteres.
- Hasta 10 URL de redirección por app, una activa a la vez; al activar una se genera su propia URL de autorización.
- state: un valor opcional que TikTok devuelve en la redirección, y que sugiere como protección contra CSRF.
disable_auto_auth=1: muestra la pantalla de revisión a los titulares que aprobaron antes los mismos permisos, a quienes TikTok de otro modo redirige de inmediato.
¿Cómo se canjea el código por tokens?
Con un POST a /tt_user/oauth2/token/ desde tu servidor, en formato JSON. client_id y client_secret son el App ID y el Secret que aparecen en Mis apps, Detalle de la app, Información básica; grant_type es authorization_code; auth_code es el código de la redirección; y redirect_uri debe ser igual a la URL de redirección del titular de la cuenta configurada en la app.
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/tt_user/oauth2/token/' \
-H 'Content-Type: application/json' \
-d '{
"client_id": "<APP_ID>",
"client_secret": "<APP_SECRET>",
"grant_type": "authorization_code",
"auth_code": "<AUTH_CODE>",
"redirect_uri": "https://app.example.com/tiktok/callback/"
}'¿Qué contiene la respuesta del token?
Un objeto JSON con code, message, request_id y data. Un code de 0 significa que el canje funcionó, y data contiene ambos tokens y el ID de la cuenta:
access_token: el token de corta duración para llamadas a la API, válido por un día.token_type: Bearer, que TikTok describe como utilizable por cualquiera que posea el token.- scope: los permisos otorgados al token, en una sola cadena separada por comas.
expires_in: los segundos restantes antes de que expire elaccess_token, 86400 en el ejemplo de TikTok.refresh_token: el token que renueva el acceso, válido por un año; la indicación de TikTok es conservarlo.refresh_token_expires_in: los segundos restantes antes de que expire elrefresh_token.open_id: el ID específico de la aplicación de la cuenta de TikTok.
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": {
"access_token": "<ACCESS_TOKEN>",
"token_type": "Bearer",
"scope": "user.info.basic,user.info.stats,user.insights,video.list,video.insights,video.publish,comment.list,comment.list.manage",
"expires_in": 86400,
"refresh_token": "<REFRESH_TOKEN>",
"refresh_token_expires_in": 31536000,
"open_id": "<OPEN_ID>"
}
}¿Cómo se envía el token en las llamadas a la API?
En un encabezado de petición llamado Access-Token, en los endpoints de la Accounts API desde /business/get/ hasta /business/video/publish/, mientras que la cuenta se indica en business_id, con el valor de open_id de la misma respuesta. Los endpoints de OAuth funcionan al revés: /tt_user/oauth2/token/, /tt_user/oauth2/refresh_token/ y /tt_user/oauth2/revoke/ reciben client_id y client_secret de la app en un cuerpo JSON y no llevan encabezado Access-Token.
¿Cómo se renueva el token de acceso?
Con un POST a /tt_user/oauth2/refresh_token/ que incluya client_id, client_secret, grant_type con el valor refresh_token y el refresh_token guardado. La respuesta tiene los mismos campos que el primer canje: un nuevo access_token con su expires_in, un refresh_token que conservar para la siguiente renovación y los segundos que le quedan. Programa la renovación antes de las 24 horas, en lugar de esperar al error 40102.
import os, time, requests
API = "https://business-api.tiktok.com/open_api/v1.3"
def renew(refresh_token: str) -> dict:
r = requests.post(f"{API}/tt_user/oauth2/refresh_token/", json={
"client_id": os.environ["TIKTOK_APP_ID"],
"client_secret": os.environ["TIKTOK_APP_SECRET"],
"grant_type": "refresh_token",
"refresh_token": refresh_token,
}, timeout=30).json()
if r["code"] != 0: # 40103: the refresh token expired, so the owner authorizes again
raise RuntimeError(f"{r['code']}: {r['message']}")
d, now = r["data"], time.time()
return {
"access_token": d["access_token"],
"access_expires_at": now + d["expires_in"],
"refresh_token": d["refresh_token"], # keep it for the next renewal
"refresh_expires_at": now + d["refresh_token_expires_in"],
}¿Cómo se revoca el acceso?
Desde la app, con un POST a /tt_user/oauth2/revoke/ con client_id, client_secret y el access_token a revocar; si funciona devuelve code 0 con un objeto data vacío. Desde la cuenta, el titular abre la app de TikTok, va a Configuración y privacidad, Seguridad, Gestionar permisos de apps, elige la app y selecciona Eliminar acceso. Una vez revocada la autorización, TikTok deja de enviar a la app los eventos comment.update de esa cuenta.
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/tt_user/oauth2/revoke/' \
-H 'Content-Type: application/json' \
-d '{"client_id": "<APP_ID>", "client_secret": "<APP_SECRET>", "access_token": "<ACCESS_TOKEN>"}'
# {"code": 0, "message": "OK", "request_id": "<REQUEST_ID>", "data": {}}¿Cómo se inspecciona un token?
Con un POST a /tt_user/token_info/get/, que no necesita permiso propio: envía app_id y el access_token, y data devuelve app_id, scope y creator_id. scope enumera lo que otorgó el titular, y creator_id es el ID específico de la aplicación de la cuenta, el valor que las llamadas a la Accounts API toman como business_id. Las referencias de TikTok remiten aquí cuando un campo necesita un scope que el token podría no tener.
¿Qué errores provienen de los tokens?
TikTok los coloca en el campo code de la respuesta, normalmente con estado HTTP 200, así que revisa code antes de confiar en una llamada. Los códigos de retorno vinculados a los tokens y a su canje:
- 40102: el
access_tokenha expirado; renuévalo y vuelve a llamar. - 40103: el
refresh_tokenha expirado; solo una nueva autorización del titular lo reemplaza. - 40104: la petición no llevaba
access_token. - 40105: el
access_tokenno es válido o es incorrecto. - 40107: el
refresh_tokenno es válido o es incorrecto, por ejemplo uno enviado para renovar un token de Marketing API, que nunca expira. - 40110: el código de autorización fue cancelado, ya se usó o ha expirado.
- 40131: error de autenticación en los dos endpoints de token, por un App ID o Secret incorrecto, un código expirado, o un
refresh_tokenno válido o expirado.
¿Qué renueva easyCoexistence por ti?
Todo lo que sigue al inicio de sesión. easyCoexistence canjea el código en cuanto TikTok redirige de vuelta, guarda ambos tokens cifrados y renueva el access_token por sí mismo: antes de una llamada cuando quedan menos de 15 minutos, y durante la comprobación que hace en cada cuenta cada unas 6 horas cuando quedan menos de 8 horas. Cada renovación guarda el nuevo refresh_token y su vencimiento, y las llamadas que llegan juntas comparten una sola renovación.
- Token rechazado: cuando TikTok responde 40102, 40104 o 40105, la conexión se marca para reconectar y el titular recibe un correo; los usuarios de la Partner API además reciben channel.disconnected.
- Tu propio código:
get_social_credentials, o GET /channels/{id}?credentials=1 en la Partner API, devuelve el token vigente contoken_expires_at, así que obténlo en cada tarea. - Eliminación: al quitar la conexión en el panel, o con DELETE /channels/{id}, se revoca el token en TikTok a través de /
tt_user/oauth2/revoke/.
Errores comunes
- Canjear el código de autorización en el navegador. El canje envía el client_secret de la app, así que hazlo desde tu servidor, dentro de los 10 minutos posteriores a la redirección.
- Leer expires_in como una fecha. Contiene los segundos restantes, así que súmalos a la hora de la respuesta para saber cuándo expira el token.
- Revocar con el refresh_token. /tt_user/oauth2/revoke/ recibe el access_token, junto con el client_id y el client_secret de la app.
- Tratar la ausencia de la pantalla de consentimiento como un fallo. TikTok omite la pantalla de revisión para los permisos que el titular aprobó antes; añade disable_auto_auth=1 para mostrarla de nuevo.
Desde US$ 9 hasta US$ 0.75 por conexión al mes, bajando a medida que añades conexiones, con los primeros 3 días gratis.
Preguntas frecuentes
¿Cuánto dura un token de acceso de la API de TikTok para negocios?
24 horas. Cada respuesta del token indica los segundos restantes en expires_in, y el refresh_token, válido por un año, lo renueva.
¿El endpoint de renovación de TikTok necesita redirect_uri?
Su tabla de parámetros enumera client_id, client_secret, grant_type y refresh_token, sin redirect_uri, aunque la guía de autenticación de TikTok indica que sus endpoints de token requieren redirect_uri.
¿Revocar un token de TikTok detiene sus webhooks?
Sí. TikTok deja de enviar a la app eventos comment.update de esa cuenta hasta que el titular vuelva a autorizar la app.
¿De dónde sale el business_id de TikTok?
De open_id en la respuesta del token, que las llamadas a la Accounts API toman como business_id. /tt_user/token_info/get/ devuelve el mismo ID como creator_id.
Sigue leyendo
Conecta tu primer canal en dos minutos.
Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.
- 3 días gratis
- Cancela cuando quieras
- Solo APIs oficiales
- Monitorizado 24/7
Verificado el