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 viaja no cabeçalho Access-Token. Uma aplicação obtém-no trocando o código de autorização do titular em /tt_user/oauth2/token/, juntamente com um token de atualizaçã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 âmbitos concedidos em /tt_user/token_info/get/.
O easyCoexistence troca o código quando uma conta da TikTok inicia sessão, renova o token de 24 horas antes de expirar e verifica a conta cerca de cada 6 horas, para que o Claude, o ChatGPT ou o seu próprio código chamem a TikTok com um token atual, que o get_social_credentials entrega aos seus scripts.
Duração de um token de acesso de conta da TikTok; cada resposta de token indica os segundos que faltam em expires_in.
Validade do token de atualização emitido com ele; refresh_token_expires_in indica os segundos que faltam.
Tempo de validade do código de autorização no redirecionamento; só pode ser trocado uma vez.
O ID específico da aplicação da conta, devolvido com cada token e enviado como business_id nas chamadas da Accounts API.
O token_type devolvido pela TikTok: quem tiver o token pode usá-lo para aceder aos recursos da conta.
O ID da conta que /tt_user/token_info/get/ devolve junto ao âmbito do token, utilizável como business_id nas chamadas da Accounts API.
Como chega o código de autorização à sua aplicação?
Através do URL de autorização do titular da conta TikTok, que a TikTok gera para uma aplicação de programador em My Apps, App Detail, Basic Information, depois de a aplicação ter a permissão TikTok Accounts. O titular da conta abre-o, revê as permissões e aprova-as. A TikTok envia então o navegador para o URL de redirecionamento da aplicação, com um auth_code acrescentado, bem como qualquer valor state que o URL de autorização tivesse. Esse código é válido durante 10 minutos e para uma única troca.
- URL de redirecionamento: absoluto, começando por https://, terminando em /, sem query string, âncora ou porta, e com 10 a 512 caracteres.
- Até 10 URLs de redirecionamento por aplicação, um ativo de cada vez; ativar um gera o seu próprio URL de autorização.
- state: um valor opcional que a TikTok devolve no redirecionamento, e que sugere como proteção contra CSRF.
disable_auto_auth=1: mostra a página de revisão aos titulares que já tinham aprovado as mesmas permissões, a quem a TikTok de outro modo redireciona de imediato.
Como se troca o código pelos 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 indicados em My Apps, App Detail, Basic Information; grant_type é authorization_code; auth_code é o código do redirecionamento; e redirect_uri tem de ser igual ao URL de redirecionamento do titular da conta TikTok definido na aplicação.
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 contém a resposta do token?
Um objeto JSON com code, message, request_id e data. Um code de 0 significa que a troca funcionou, e data traz os dois tokens e o ID da conta:
access_token: o token de curta duração para chamadas à API, válido por um dia.token_type: Bearer, que a TikTok descreve como utilizável por quem tiver o token.- scope: as permissões concedidas ao token, numa única cadeia separada por vírgulas.
expires_in: os segundos que faltam até aoaccess_tokenexpirar, 86400 no exemplo da TikTok.refresh_token: o token que renova o acesso, válido por um ano; a nota da TikTok é guardá-lo.refresh_token_expires_in: os segundos que faltam até aorefresh_tokenexpirar.open_id: o ID específico da aplicação da conta 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 é enviado o token nas chamadas à API?
Num cabeçalho de pedido chamado Access-Token, nos endpoints da Accounts API, desde /business/get/ até /business/video/publish/, enquanto a conta é indicada em business_id, com o valor de open_id da mesma resposta. Os endpoints 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 da aplicação num corpo JSON, e não um cabeçalho Access-Token.
Como se renova o token de acesso?
Com um POST para /tt_user/oauth2/refresh_token/ com client_id, client_secret, grant_type com o valor refresh_token e o refresh_token guardado. A resposta tem os mesmos campos da primeira troca: um novo access_token com o respetivo expires_in, um refresh_token a guardar para a próxima renovação e os segundos que lhe restam. Agende a renovação antes das 24 horas, em vez de esperar pelo 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 se revoga o acesso?
A partir da aplicação, com um POST para /tt_user/oauth2/revoke/ com client_id, client_secret e o access_token a revogar; o sucesso devolve code 0 com um objeto data vazio. A partir da conta, o titular abre a aplicação TikTok, vai a Definições e privacidade, Segurança, Gerir permissões da aplicação, escolhe a aplicação e seleciona Remover acesso. Depois de a autorização ser revogada, a TikTok deixa de enviar à aplicação 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 se inspeciona um token?
Com um POST para /tt_user/token_info/get/, que não precisa de permissão própria: envie app_id e o access_token, e data devolve app_id, scope e creator_id. scope lista o que o titular concedeu, e creator_id é o ID específico da aplicação da conta, o valor que as chamadas da Accounts API recebem como business_id. As referências da TikTok encaminham os programadores para aqui sempre que um campo exige um âmbito que o token pode não ter.
Que erros vêm dos tokens?
A TikTok coloca-os no campo code da resposta, normalmente com o estado HTTP 200, por isso verifique code antes de confiar numa chamada. Os códigos de retorno ligados aos tokens e à respetiva troca:
- 40102: o access token expirou; renove-o e volte a chamar.
- 40103: o refresh token expirou; só uma nova autorização do titular o substitui.
- 40104: o pedido não trazia 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, devido a um App ID ou secret errado, a um código expirado ou a um refresh token inválido ou expirado.
O que renova o easyCoexistence por si?
Tudo depois do início de sessão. O easyCoexistence troca o código logo que a TikTok redireciona de volta, guarda os dois tokens cifrados e renova ele próprio o access token: antes de uma chamada quando faltam menos de 15 minutos, e na verificação de cada conta, feita cerca de cada 6 horas quando faltam menos de 8 horas. Cada renovação guarda o novo refresh token e a respetiva validade, e as chamadas que chegam juntas partilham uma só renovação.
- Token rejeitado: quando a TikTok responde 40102, 40104 ou 40105, a ligação fica marcada para voltar a ligar, e o titular recebe um email; os utilizadores da Partner API recebem também channel.disconnected.
- O seu próprio código:
get_social_credentials, ou GET /channels/{id}?credentials=1 na Partner API, devolve o token atual comtoken_expires_at, por isso obtenha-o em cada tarefa. - Remoção: remover a ligação no painel, ou com DELETE /channels/{id}, revoga o token na TikTok através de /
tt_user/oauth2/revoke/.
Erros comuns
- Trocar o código de autorização no navegador. A troca envia o client_secret da aplicação, por isso faça-a no servidor, dentro de 10 minutos após o redirecionamento.
- Ler expires_in como uma data. Indica os segundos que faltam, por isso some-os à hora da resposta para saber quando o token expira.
- Revogar com o refresh token. /tt_user/oauth2/revoke/ recebe o access_token, juntamente com o client_id e o client_secret da aplicação.
- Tratar a falta de um ecrã de consentimento como falha. A TikTok salta a página de revisão das permissões que o titular já aprovou; acrescente disable_auto_auth=1 para a mostrar de novo.
De US$ 9 até US$ 0.75 por ligação por mês, a descer à medida que acrescenta ligações, com os primeiros 3 dias grátis.
Perguntas frequentes
Quanto tempo dura um token de acesso da TikTok API for Business?
24 horas. Cada resposta de token indica os segundos que faltam em expires_in, e o token de atualização, válido por um ano, renova-o.
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 os seus endpoints de token exigem redirect_uri.
Revogar um token da TikTok interrompe os webhooks?
Sim. A TikTok deixa de enviar à aplicação eventos comment.update dessa conta até que o titular volte a autorizar a aplicação.
De onde vem o business_id da TikTok?
Do open_id da 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 a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em