AccediInizia la prova gratuita
easyCoexistence API ufficiali

Token di accesso di TikTok API for Business: 24 ore, rinnovo e revoca

Un token di accesso dell'API for Business di TikTok dura 24 ore e viaggia nell'header Access-Token. Un'app lo ottiene scambiando il codice di autorizzazione del titolare presso /tt_user/oauth2/token/, insieme a un refresh token che dura un anno e rinnova l'accesso presso /tt_user/oauth2/refresh_token/. Lo si revoca presso /tt_user/oauth2/revoke/ e si elencano gli scope concessi presso /tt_user/token_info/get/.

easyCoexistence scambia il codice quando un account TikTok accede, rinnova il token da 24 ore prima che scada e controlla l'account circa ogni 6 ore, così Claude, ChatGPT o il tuo codice chiamano TikTok con un token aggiornato, che get_social_credentials consegna ai tuoi script.

24 hours

Durata di un token di accesso dell'account TikTok; ogni risposta del token indica i secondi residui in expires_in.

1 year

Validità del refresh token emesso insieme; refresh_token_expires_in ne indica i secondi residui.

10 minutes

Per quanto tempo resta valido il codice di autorizzazione nel redirect; può essere scambiato una sola volta.

open_id

L'ID specifico dell'applicazione dell'account, restituito con ogni token e inviato come business_id nelle chiamate all'Accounts API.

Bearer

Il token_type restituito da TikTok: chi possiede il token può usarlo per accedere alle risorse dell'account.

creator_id

L'ID dell'account che /tt_user/token_info/get/ restituisce accanto allo scope del token, utilizzabile come business_id nelle chiamate all'Accounts API.

Come arriva il codice di autorizzazione alla tua app?

Tramite l'URL di autorizzazione del titolare dell'account TikTok, che TikTok genera per un'app sviluppatore in My Apps, App Detail, Basic Information, una volta che l'app ha ottenuto il permesso TikTok Accounts. Il titolare lo apre, verifica i permessi e li approva. TikTok reindirizza poi il browser all'URL di redirect dell'app con un auth_code aggiunto, insieme a eventuali valori state presenti nell'URL di autorizzazione. Il codice è valido per 10 minuti e per un solo scambio.

  • URL di redirect: assoluto, che inizia con https://, termina con /, non contiene stringa di query, ancora o porta, e ha una lunghezza da 10 a 512 caratteri.
  • Fino a 10 URL di redirect per app, uno attivo alla volta; attivarne uno genera il proprio URL di autorizzazione.
  • state: valore facoltativo che TikTok restituisce nel redirect, suggerito come protezione contro il CSRF.
  • disable_auto_auth=1: mostra la pagina di revisione ai titolari che hanno già approvato gli stessi permessi, che altrimenti TikTok reindirizza subito.

Come scambi il codice con i token?

Con una POST a /tt_user/oauth2/token/ dal tuo server, in formato JSON. client_id e client_secret sono l'App ID e il Secret mostrati in My Apps, App Detail, Basic Information; grant_type è authorization_code; auth_code è il codice del redirect; redirect_uri deve coincidere con l'URL di redirect del titolare impostato nell'app.

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/"
  }'

Cosa contiene la risposta con i token?

Un oggetto JSON con code, message, request_id e data. Un code pari a 0 significa che lo scambio è riuscito, e data contiene entrambi i token e l'ID dell'account:

  • access_token: il token di breve durata per le chiamate API, valido per un giorno.
  • token_type: Bearer, che TikTok descrive come utilizzabile da chiunque possieda il token.
  • scope: i permessi concessi al token, come stringa unica separata da virgole.
  • expires_in: i secondi che mancano alla scadenza dell'access token, 86400 nell'esempio di TikTok.
  • refresh_token: il token che rinnova l'accesso, valido per un anno; la nota di TikTok è di conservarlo.
  • refresh_token_expires_in: i secondi che mancano alla scadenza del refresh token.
  • open_id: l'ID specifico dell'applicazione dell'account 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>"
  }
}

Come viene inviato il token nelle chiamate API?

Nell'header Access-Token, negli endpoint dell'Accounts API da /business/get/ a /business/video/publish/, mentre l'account viene indicato in business_id, impostato sull'open_id della stessa risposta. Gli endpoint OAuth funzionano al contrario: /tt_user/oauth2/token/, /tt_user/oauth2/refresh_token/ e /tt_user/oauth2/revoke/ ricevono client_id e client_secret dell'app in un corpo JSON, senza header Access-Token.

Come rinnovi l'access token?

Con una POST a /tt_user/oauth2/refresh_token/ che contiene client_id, client_secret, grant_type impostato su refresh_token e il refresh_token salvato. La risposta ha gli stessi campi del primo scambio: un nuovo access_token con il suo expires_in, un refresh_token da conservare per il rinnovo successivo e i secondi che gli restano. Pianifica il rinnovo prima delle 24 ore, invece di aspettare l'errore 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"],
    }

Come revochi l'accesso?

Dall'app, con una POST a /tt_user/oauth2/revoke/ che contiene client_id, client_secret e l'access_token da revocare; in caso di successo restituisce code 0 con un oggetto data vuoto. Dall'account, il titolare apre l'app TikTok, va in Impostazioni e privacy, Sicurezza, Gestisci autorizzazioni delle app, sceglie l'app e seleziona Rimuovi accesso. Una volta revocata l'autorizzazione, TikTok smette di inviare all'app gli eventi comment.update per quell'account.

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": {}}

Come controlli un token?

Con una POST a /tt_user/token_info/get/, che non richiede un permesso proprio: invii app_id e access_token, e data restituisce app_id, scope e creator_id. scope elenca ciò che il titolare ha concesso, e creator_id è l'ID specifico dell'applicazione dell'account, il valore che le chiamate Accounts API usano come business_id. La documentazione di TikTok rimanda a questo endpoint ogni volta che un campo richiede uno scope che il token potrebbe non avere.

Quali errori derivano dai token?

TikTok li inserisce nel campo code della risposta, di solito con stato HTTP 200, quindi controlla code prima di considerare valida una chiamata. I codici di ritorno legati ai token e al loro scambio:

  • 40102: l'access token è scaduto; rinnovalo e richiama.
  • 40103: il refresh token è scaduto; solo una nuova autorizzazione del titolare lo sostituisce.
  • 40104: la richiesta non conteneva alcun access token.
  • 40105: l'access token non è valido o è errato.
  • 40107: il refresh token non è valido o è errato, per esempio quello inviato per rinnovare un token della Marketing API, che non scade mai.
  • 40110: il codice di autorizzazione è stato annullato, è già stato usato o è scaduto.
  • 40131: errore di autenticazione agli endpoint dei due token, causato da App ID o secret errati, da un codice scaduto, o da un refresh token non valido o scaduto.

Cosa rinnova easyCoexistence per te?

Tutto ciò che viene dopo l'accesso. easyCoexistence scambia il codice non appena TikTok ti reindirizza, salva entrambi i token cifrati e rinnova da sola l'access token: prima di una chiamata quando restano meno di 15 minuti, e durante il controllo che esegue circa ogni 6 ore su ogni account quando restano meno di 8 ore. Ogni rinnovo salva il nuovo refresh token e la sua scadenza, e le chiamate arrivate insieme condividono un solo rinnovo.

  • Token rifiutato: quando TikTok risponde 40102, 40104 o 40105, la connessione viene segnata per la riconnessione e il titolare riceve un'e-mail; gli utenti della Partner API ricevono anche channel.disconnected.
  • Il tuo codice: get_social_credentials, oppure GET /channels/{id}?credentials=1 sulla Partner API, restituisce il token corrente con token_expires_at, quindi recuperalo a ogni esecuzione.
  • Rimozione: eliminare la connessione dalla dashboard, oppure con DELETE /channels/{id}, revoca il token presso TikTok tramite /tt_user/oauth2/revoke/.

Errori comuni

  • Scambiare il codice di autorizzazione nel browser. Lo scambio invia il client_secret dell'app, quindi fallo dal tuo server, entro 10 minuti dal redirect.
  • Leggere expires_in come una data. Contiene i secondi residui, quindi sommali all'ora della risposta per sapere quando scade il token.
  • Revocare con il refresh token. /tt_user/oauth2/revoke/ richiede l'access_token, insieme a client_id e client_secret dell'app.
  • Considerare l'assenza della schermata di consenso come un errore. TikTok salta la pagina di revisione per i permessi già approvati dal titolare; aggiungi disable_auto_auth=1 per mostrarla di nuovo.
Farlo con EasyCoexistence

US$ 9 a US$ 0.75 per connessione al mese, con prezzo che scende man mano che aggiungi connessioni, e la prova gratuita di 3 giorni.

Domande frequenti

Quanto dura un access token dell'API for Business di TikTok?

24 ore. Ogni risposta con i token indica i secondi residui in expires_in, e il refresh token, valido per un anno, lo rinnova.

L'endpoint di rinnovo di TikTok richiede redirect_uri?

La sua tabella dei parametri elenca client_id, client_secret, grant_type e refresh_token, senza redirect_uri, anche se la guida all'autenticazione di TikTok afferma che i suoi endpoint dei token richiedono redirect_uri.

Revocare un token TikTok blocca i suoi webhook?

Sì. TikTok non invia più all'app eventi comment.update per quell'account finché il titolare non autorizza di nuovo l'app.

Da dove arriva il business_id di TikTok?

Dall'open_id nella risposta con i token, che le chiamate Accounts API usano come business_id. /tt_user/token_info/get/ restituisce lo stesso ID come creator_id.

Continua a leggere

Collega il tuo primo canale in due minuti.

Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.

  • 3 giorni gratis
  • Disdici quando vuoi
  • Solo API ufficiali
  • Monitorato 24/7

Verificato il