Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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.

24 hours

Duração de um token de acesso de conta da TikTok; cada resposta de token indica os segundos que faltam em expires_in.

1 year

Validade do token de atualização emitido com ele; refresh_token_expires_in indica os segundos que faltam.

10 minutes

Tempo de validade do código de autorização no redirecionamento; só pode ser trocado uma vez.

open_id

O ID específico da aplicação da conta, devolvido com cada token e enviado como business_id nas chamadas da Accounts API.

Bearer

O token_type devolvido pela TikTok: quem tiver o token pode usá-lo para aceder aos recursos da conta.

creator_id

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.

Exchange the authorization code
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é ao access_token expirar, 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é ao refresh_token expirar.
  • open_id: o ID específico da aplicação da conta TikTok.
A token response (scope shortened)
{
  "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.

Renew a TikTok account access token in Python
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.

Revoke a TikTok account access token
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 com token_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.
Fazer isto com a EasyCoexistence

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