Tokens de acesso da TikTok API for Business: 24 horas, renovação e revogação
Um token de acesso da TikTok API for Business dura 24 horas e é enviado no cabeçalho Access-Token. Um app o obtém trocando o código de autorização do titular em /tt_user/oauth2/token/, junto com um token de renovação que dura um ano e renova o acesso em /tt_user/oauth2/refresh_token/. Revogue-o em /tt_user/oauth2/revoke/ e liste os escopos concedidos em /tt_user/token_info/get/.
O easyCoexistence troca o código quando uma conta da TikTok faz login, renova o token de 24 horas antes que ele expire e verifica a conta aproximadamente a cada 6 horas, para que o Claude, o ChatGPT ou o seu próprio código chame a TikTok com um token atual, que get_social_credentials entrega aos seus scripts.
Duração de um token de acesso de conta da TikTok; cada resposta de token informa os segundos restantes em expires_in.
Validade do token de renovação emitido junto; refresh_token_expires_in informa seus segundos restantes.
Por quanto tempo o código de autorização do redirecionamento permanece válido; ele pode ser trocado apenas uma vez.
O ID específico do app da conta, devolvido com cada token e enviado como business_id nas chamadas da Accounts API.
O token_type que a TikTok devolve: quem possui o token pode usá-lo para acessar os recursos da conta.
O ID da conta que /tt_user/token_info/get/ devolve ao lado do escopo do token, utilizável como business_id nas chamadas da Accounts API.
Como o código de autorização chega ao seu app?
Pela URL de autorização do titular da conta da TikTok, que a TikTok gera para um app de desenvolvedor em My Apps, App Detail, Basic Information, assim que o app tem a permissão TikTok Accounts. O titular da conta a abre, revisa as permissões e as aprova. Em seguida, a TikTok envia o navegador para a URL de redirecionamento do app com um auth_code anexado, além de qualquer valor state que a URL de autorização trouxer. Esse código vale por 10 minutos e para uma única troca.
- URL de redirecionamento: absoluta, começando com https://, terminando em /, sem query string, âncora ou porta, e com 10 a 512 caracteres.
- Até 10 URLs de redirecionamento por app, uma ativa por vez; ativar uma gera a própria URL de autorização.
- state: um valor opcional que a TikTok repete no redirecionamento, o qual ela sugere como proteção contra CSRF.
disable_auto_auth=1: mostra a tela de revisão aos titulares que aprovaram as mesmas permissões antes, que a TikTok de outra forma redireciona de imediato.
Como você troca o código por tokens?
Com um POST para /tt_user/oauth2/token/ a partir do seu servidor, em JSON. client_id e client_secret são o App ID e o Secret exibidos em My Apps, App Detail, Basic Information; grant_type é authorization_code; auth_code é o código do redirecionamento; e redirect_uri precisa ser igual à URL de redirecionamento do titular da conta definida no 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/"
}'O que a resposta do token contém?
Um objeto JSON com code, message, request_id e data. Um code igual a 0 significa que a troca funcionou, e data traz os dois tokens e o ID da conta:
access_token: o token de curto prazo para chamadas de API, válido por um dia.token_type: Bearer, que a TikTok descreve como utilizável por qualquer pessoa que possua o token.- scope: as permissões concedidas ao token, em uma única string separada por vírgulas.
expires_in: os segundos restantes até oaccess_tokenexpirar, 86400 no exemplo da TikTok.refresh_token: o token que renova o acesso, válido por um ano; a orientação da TikTok é guardá-lo.refresh_token_expires_in: os segundos restantes até orefresh_tokenexpirar.open_id: o ID específico do app para a conta da 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>"
}
}Como o token é enviado nas chamadas de API?
Em um cabeçalho de requisição chamado Access-Token, nos endpoints da Accounts API, de /business/get/ até /business/video/publish/, enquanto a conta é indicada em business_id, definido como o open_id da mesma resposta. Os endpoints de OAuth funcionam ao contrário: /tt_user/oauth2/token/, /tt_user/oauth2/refresh_token/ e /tt_user/oauth2/revoke/ recebem o client_id e o client_secret do app em um corpo JSON e nenhum cabeçalho Access-Token.
Como você renova o token de acesso?
Com um POST para /tt_user/oauth2/refresh_token/ contendo client_id, client_secret, grant_type definido como refresh_token e o refresh_token armazenado. A resposta tem os mesmos campos da primeira troca: um novo access_token com seu expires_in, um refresh_token a guardar para a próxima renovação e os segundos que ele ainda tem. Agende a renovação antes das 24 horas, em vez de esperar o erro 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"],
}Como você revoga o acesso?
Pelo app, com um POST para /tt_user/oauth2/revoke/ contendo client_id, client_secret e o access_token a revogar; o sucesso retorna code 0 com um objeto data vazio. Pela conta, o titular abre o app da TikTok, vai em Settings and privacy, Security, Manage app permissions, escolhe o app e seleciona Remove access. Depois que a autorização é revogada, a TikTok deixa de enviar ao app os eventos comment.update dessa conta.
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": {}}Como você inspeciona um token?
Com um POST para /tt_user/token_info/get/, que não exige permissão própria: envie app_id e o access_token, e data retorna app_id, scope e creator_id. scope lista o que o titular concedeu, e creator_id é o ID específico do app da conta, o valor que as chamadas da Accounts API recebem como business_id. As referências da TikTok encaminham os desenvolvedores para cá sempre que um campo precisa de um escopo que o token pode não ter.
Quais erros vêm dos tokens?
A TikTok os coloca no campo code da resposta, geralmente com status HTTP 200, então verifique code antes de confiar em uma chamada. Os códigos de retorno ligados aos tokens e à sua troca:
- 40102: o
access_tokenexpirou; renove-o e chame de novo. - 40103: o
refresh_tokenexpirou; apenas uma nova autorização do titular o substitui. - 40104: a requisição não trouxe
access_token. - 40105: o
access_tokené inválido ou incorreto. - 40107: o
refresh_tokené inválido ou incorreto, por exemplo um enviado para renovar um token da Marketing API, que nunca expira. - 40110: o código de autorização foi cancelado, já foi usado ou expirou.
- 40131: erro de autenticação nos dois endpoints de token, causado por App ID ou secret incorretos, código expirado ou
refresh_tokeninválido ou expirado.
O que o easyCoexistence renova por você?
Tudo depois do login. O easyCoexistence troca o código assim que a TikTok redireciona de volta, armazena os dois tokens criptografados e renova o access_token por conta própria: antes de uma chamada, quando restam menos de 15 minutos, e durante a verificação que roda em cada conta a cada 6 horas aproximadamente, quando restam menos de 8 horas. Cada renovação grava o novo refresh_token e a sua expiração, e as chamadas que chegam juntas compartilham uma só renovação.
- Token recusado: quando a TikTok responde 40102, 40104 ou 40105, a conexão é marcada para reconexão e o titular recebe um e-mail; usuários da Partner API também recebem channel.disconnected.
- Seu próprio código:
get_social_credentials, ou GET /channels/{id}?credentials=1 na Partner API, devolve o token atual comtoken_expires_at, então busque-o a cada execução. - Remoção: remover a conexão no painel, ou com DELETE /channels/{id}, revoga o token na TikTok por meio de /
tt_user/oauth2/revoke/.
Erros comuns
- Trocar o código de autorização no navegador. A troca envia o client_secret do app, então faça-a no seu servidor, em até 10 minutos após o redirecionamento.
- Ler expires_in como uma data. Ele contém os segundos restantes, então some-o ao horário da resposta para saber quando o token expira.
- Revogar com o refresh token. /tt_user/oauth2/revoke/ recebe o access_token, junto com o client_id e o client_secret do app.
- Tratar uma tela de consentimento ausente como falha. A TikTok pula a tela de revisão para permissões que o titular já aprovou antes; acrescente disable_auto_auth=1 para exibi-la novamente.
De US$ 9 a US$ 0.75 por conexão por mês, caindo à medida que você adiciona conexões, com os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Quanto tempo dura um token de acesso da TikTok API for Business?
24 horas. Cada resposta de token informa os segundos restantes em expires_in, e o refresh token, válido por um ano, o renova.
O endpoint de renovação da TikTok precisa de redirect_uri?
A tabela de parâmetros lista client_id, client_secret, grant_type e refresh_token, sem redirect_uri, embora o guia de autenticação da TikTok diga que seus endpoints de token exigem redirect_uri.
Revogar um token da TikTok interrompe os seus webhooks?
Sim. A TikTok deixa de enviar ao app eventos comment.update dessa conta até que o titular autorize o app novamente.
De onde vem o business_id da TikTok?
Do open_id na resposta do token, que as chamadas da Accounts API recebem como business_id. /tt_user/token_info/get/ devolve o mesmo ID como creator_id.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em