Access-tokens van de TikTok API for Business: 24 uur, vernieuwen en intrekken
Een access-token van de TikTok API for Business is 24 uur geldig en gaat mee in de header Access-Token. Een app krijgt het door de autorisatiecode van de eigenaar in te wisselen bij /tt_user/oauth2/token/, samen met een refresh-token dat een jaar geldig is en de toegang vernieuwt via /tt_user/oauth2/refresh_token/. Intrekken doe je via /tt_user/oauth2/revoke/, en de toegekende scopes bekijk je via /tt_user/token_info/get/.
easyCoexistence wisselt de code uit zodra een TikTok-account inlogt, vernieuwt het token van 24 uur voordat het verloopt en controleert het account ongeveer elke 6 uur.
Geldigheidsduur van een TikTok-accounttoken; elk tokenantwoord vermeldt de resterende seconden in expires_in.
Geldigheid van het refresh-token dat hiermee wordt uitgegeven; refresh_token_expires_in geeft het resterende aantal seconden.
Hoe lang de autorisatiecode in de redirect geldig blijft; hij kan maar één keer worden ingewisseld.
De toepassingsspecifieke ID van het account, teruggegeven bij elk token en meegestuurd als business_id bij Accounts API-aanroepen.
Het token_type dat TikTok teruggeeft: wie het token bezit, kan daarmee de bronnen van het account gebruiken.
Het account-ID dat /tt_user/token_info/get/ teruggeeft naast de scope van het token, bruikbaar als business_id bij Accounts API-aanroepen.
Hoe bereikt de autorisatiecode je app?
Via de autorisatie-URL voor de accounthouder van TikTok, die TikTok voor een developer-app genereert onder My Apps, App Detail, Basic Information zodra de app de TikTok Accounts-permissie heeft. De accounteigenaar opent de URL, bekijkt de permissies en keurt ze goed. TikTok stuurt de browser dan naar de redirect-URL van de app met een auth_code erachter, plus eventuele state-waarde die de autorisatie-URL meekreeg. Die code is 10 minuten geldig en werkt maar voor één uitwisseling.
- Redirect-URL: absoluut, begint met https://, eindigt op /, zonder querystring, anker of poort, en 10 tot 512 tekens lang.
- Tot 10 redirect-URL's per app, waarvan er één tegelijk actief is; activeren van een URL maakt er een eigen autorisatie-URL van.
- state: een optionele waarde die TikTok bij de redirect terugstuurt, en die volgens TikTok helpt tegen CSRF.
disable_auto_auth=1: toont de beoordelingspagina aan eigenaren die eerder dezelfde permissies goedkeurden, die TikTok anders meteen doorstuurt.
Hoe wissel je de code in voor tokens?
Met een POST naar /tt_user/oauth2/token/ vanaf je server, als JSON. client_id en client_secret zijn de App ID en Secret die onder My Apps, App Detail, Basic Information staan; grant_type is authorization_code; auth_code is de code uit de redirect; en redirect_uri moet gelijk zijn aan de TikTok account holder redirect-URL die in de app is ingesteld.
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/"
}'Wat bevat het tokenantwoord?
Een JSON-object met code, message, request_id en data. Een code van 0 betekent dat de uitwisseling is gelukt, en data bevat beide tokens en het ID van het account:
access_token: het kortlopende token voor API-aanroepen, één dag geldig.token_type: Bearer, waarvan TikTok omschrijft dat iedereen die het token bezit het kan gebruiken.- scope: de permissies die aan het token zijn toegekend, als één door komma's gescheiden string.
expires_in: het aantal resterende seconden tot het access-token verloopt, in het voorbeeld van TikTok 86400.refresh_token: het token dat de toegang vernieuwt, één jaar geldig; TikTok adviseert het te bewaren.refresh_token_expires_in: het aantal resterende seconden tot het refresh-token verloopt.open_id: de toepassingsspecifieke ID van het TikTok-account.
{
"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>"
}
}Hoe wordt het token meegestuurd bij API-aanroepen?
In een header met de naam Access-Token, bij Accounts API-endpoints van /business/get/ tot /business/video/publish/. Het account zelf wordt aangegeven in business_id, ingesteld op de open_id uit hetzelfde antwoord. De OAuth-endpoints werken andersom: /tt_user/oauth2/token/, /tt_user/oauth2/refresh_token/ en /tt_user/oauth2/revoke/ nemen de client_id en client_secret van de app in een JSON-body en geen Access-Token-header.
Hoe vernieuw je het access-token?
Met een POST naar /tt_user/oauth2/refresh_token/ met client_id, client_secret, grant_type op refresh_token en het opgeslagen refresh_token. Het antwoord heeft dezelfde velden als de eerste uitwisseling: een nieuw access_token met zijn expires_in, een refresh_token om voor de volgende vernieuwing te bewaren en de resterende seconden daarvan. Plan de vernieuwing vóór de 24 uur in, in plaats van te wachten op foutcode 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"],
}Hoe trek je toegang in?
Vanuit de app, met een POST naar /tt_user/oauth2/revoke/ met client_id, client_secret en het access_token dat moet worden ingetrokken; bij succes geeft het code 0 terug met een leeg data-object. Vanuit het account opent de eigenaar de TikTok-app, gaat naar Instellingen en privacy, Beveiliging, Appmachtigingen beheren, kiest de app en kiest Toegang verwijderen. Zodra de autorisatie is ingetrokken, stuurt TikTok de app geen comment.update-events meer voor dat account.
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": {}}Hoe controleer je een token?
Met een POST naar /tt_user/token_info/get/, waarvoor geen eigen permissie nodig is: stuur app_id en het access_token mee, en data geeft app_id, scope en creator_id terug. scope somt op wat de eigenaar heeft toegekend, en creator_id is de toepassingsspecifieke ID van het account, de waarde die Accounts API-aanroepen als business_id gebruiken. De referenties van TikTok sturen ontwikkelaars hierheen wanneer een veld een scope vereist die het token mogelijk mist.
Welke fouten komen uit tokens voort?
TikTok zet ze in het veld code van het antwoord, meestal onder HTTP-status 200, dus controleer code voordat je een aanroep vertrouwt. De foutcodes die bij tokens en hun uitwisseling horen:
- 40102: het access-token is verlopen; vernieuw het en roep opnieuw aan.
- 40103: het refresh-token is verlopen; alleen een nieuwe autorisatie door de eigenaar vervangt het.
- 40104: het verzoek bevatte geen access-token.
- 40105: het access-token is ongeldig of onjuist.
- 40107: het refresh-token is ongeldig of onjuist, bijvoorbeeld een token dat is gebruikt om een Marketing API-token te vernieuwen, die nooit verloopt.
- 40110: de autorisatiecode is geannuleerd, al gebruikt of verlopen.
- 40131: een authenticatiefout bij de twee tokenendpoints, door een verkeerde app-ID of secret, een verlopen code, of een ongeldig of verlopen refresh-token.
Wat vernieuwt easyCoexistence voor je?
Alles na het inloggen. easyCoexistence wisselt de code zodra TikTok terugstuurt, slaat beide tokens versleuteld op en vernieuwt het access-token zelf: vóór een aanroep als er minder dan 15 minuten over is, en tijdens de controle die ongeveer elke 6 uur op elk account draait als er minder dan 8 uur over is. Elke vernieuwing slaat het nieuwe refresh-token en de vervaldatum op, en aanroepen die samen binnenkomen delen één vernieuwing.
- Afgewezen token: als TikTok 40102, 40104 of 40105 antwoordt, wordt de verbinding gemarkeerd om opnieuw te verbinden en krijgt de eigenaar een e-mail; gebruikers van de Partner API ontvangen ook channel.disconnected.
- Je eigen code:
get_social_credentials, of GET /channels/{id}?credentials=1 op de Partner API, geeft het huidige token terug mettoken_expires_at, dus haal het per taak op. - Verwijderen: het verwijderen van de verbinding in het dashboard, of met DELETE /channels/{id}, trekt het token in bij TikTok via /
tt_user/oauth2/revoke/.
Veelgemaakte fouten
- De autorisatiecode in de browser inwisselen. De uitwisseling stuurt de client_secret van de app mee, dus doe dit op je server, binnen 10 minuten na de redirect.
- expires_in lezen als datum. Het bevat de resterende seconden, dus tel het op bij het tijdstip van het antwoord om te weten wanneer het token verloopt.
- Intrekken met het refresh-token. /tt_user/oauth2/revoke/ vraagt om het access_token, samen met de client_id en client_secret van de app.
- Een ontbrekend toestemmingsscherm als fout zien. TikTok slaat de beoordelingspagina over voor permissies die de eigenaar eerder goedkeurde; voeg disable_auto_auth=1 toe om hem weer te tonen.
Zo roepen Claude, ChatGPT of je eigen code TikTok aan met een actueel token, dat get_social_credentials aan je scripts geeft. Van US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je meer verbindingen toevoegt, met de eerste 3 dagen als gratis proefperiode.
Veelgestelde vragen
Hoe lang geldt een TikTok API for Business access-token?
24 uur. Elk tokenantwoord geeft de resterende seconden in expires_in, en het refresh-token, dat een jaar geldig is, vernieuwt het.
Heeft het TikTok refresh-endpoint redirect_uri nodig?
De parametertabel noemt client_id, client_secret, grant_type en refresh_token, zonder redirect_uri, al stelt de authenticatiegids van TikTok dat de token-endpoints redirect_uri vereisen.
Stopt het intrekken van een TikTok-token de webhooks?
Ja. TikTok stuurt de app geen comment.update-events meer voor dat account totdat de eigenaar de app opnieuw autoriseert.
Waar komt de TikTok business_id vandaan?
Uit open_id in het tokenantwoord, dat Accounts API-aanroepen als business_id gebruiken. /tt_user/token_info/get/ geeft dezelfde ID terug als creator_id.
Lees verder
Koppel je eerste kanaal in twee minuten.
Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.
- 3 dagen gratis
- Op elk moment opzegbaar
- Alleen officiële API's
- 24/7 bewaakt
Geverifieerd op