AnmeldenKostenlose Testphase starten
easyCoexistence Offizielle APIs

TikTok API for Business Access-Tokens: 24 Stunden, Erneuerung und Widerruf

Ein Access-Token der TikTok API for Business ist 24 Stunden gültig und wird im Header Access-Token übertragen. Eine App erhält es, indem sie den Autorisierungscode des Inhabers unter /tt_user/oauth2/token/ austauscht, zusammen mit einem Refresh-Token, das ein Jahr gültig ist und den Zugriff unter /tt_user/oauth2/refresh_token/ erneuert. Widerrufen wird es unter /tt_user/oauth2/revoke/, die gewährten Scopes lassen sich unter /tt_user/token_info/get/ abfragen.

easyCoexistence tauscht den Code, sobald sich ein TikTok-Konto anmeldet, erneuert das 24-Stunden-Token, bevor es abläuft, und prüft das Konto etwa alle 6 Stunden.

24 hours

Gültigkeitsdauer eines Access-Tokens für TikTok-Konten; jede Token-Antwort nennt die verbleibenden Sekunden in expires_in.

1 year

Gültigkeit des Refresh-Tokens, das damit ausgestellt wird; refresh_token_expires_in gibt die verbleibenden Sekunden an.

10 minutes

Wie lange der Autorisierungscode in der Weiterleitung gültig bleibt; er kann nur einmal ausgetauscht werden.

open_id

Die anwendungsspezifische ID des Kontos, die mit jedem Token zurückkommt und bei Accounts-API-Aufrufen als business_id gesendet wird.

Bearer

Der token_type, den TikTok zurückgibt: Wer das Token besitzt, kann damit auf die Ressourcen des Kontos zugreifen.

creator_id

Die Konto-ID, die /tt_user/token_info/get/ neben dem Scope des Tokens zurückgibt und bei Accounts-API-Aufrufen als business_id verwendet werden kann.

Wie gelangt der Autorisierungscode zu Ihrer App?

Über die Autorisierungs-URL für den TikTok-Kontoinhaber, die TikTok für eine Entwickler-App unter My Apps, App Detail, Basic Information erzeugt, sobald die App die Berechtigung TikTok Accounts besitzt. Der Kontoinhaber öffnet sie, prüft die Berechtigungen und genehmigt sie. TikTok leitet den Browser dann zur Redirect-URL der App weiter und hängt einen auth_code an, dazu jeden state-Wert, den die Autorisierungs-URL enthielt. Dieser Code ist 10 Minuten lang gültig und nur für einen einzigen Austausch.

  • Redirect-URL: absolut, beginnt mit https://, endet mit /, ohne Abfragestring, Anker oder Port, und 10 bis 512 Zeichen lang.
  • Bis zu 10 Redirect-URLs pro App, davon eine aktiv; die Aktivierung einer URL erzeugt eine eigene Autorisierungs-URL.
  • state: ein optionaler Wert, den TikTok beim Redirect zurückgibt; TikTok empfiehlt ihn als Schutz gegen CSRF.
  • disable_auto_auth=1: zeigt die Prüfseite Kontoinhabern, die dieselben Berechtigungen schon einmal genehmigt haben und die TikTok sonst sofort weiterleitet.

Wie tauschen Sie den Code gegen Tokens?

Mit einem POST an /tt_user/oauth2/token/ von Ihrem Server aus, als JSON. client_id und client_secret sind die App ID und das Secret, die unter My Apps, App Detail, Basic Information angezeigt werden; grant_type ist authorization_code; auth_code ist der Code aus der Weiterleitung; und redirect_uri muss der in der App hinterlegten Redirect-URL des Kontoinhabers entsprechen.

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

Was enthält die Token-Antwort?

Ein JSON-Objekt mit code, message, request_id und data. Ein code von 0 bedeutet, dass der Austausch funktioniert hat; data enthält beide Tokens und die ID des Kontos:

  • access_token: das kurzlebige Token für API-Aufrufe, einen Tag gültig.
  • token_type: Bearer, das TikTok so beschreibt, dass jeder, der das Token besitzt, es verwenden kann.
  • scope: die dem Token gewährten Berechtigungen, als eine durch Kommata getrennte Zeichenkette.
  • expires_in: die verbleibenden Sekunden bis zum Ablauf des Access-Tokens, im Beispiel von TikTok 86400.
  • refresh_token: das Token, das den Zugriff erneuert und ein Jahr gültig ist; TikTok rät, es aufzubewahren.
  • refresh_token_expires_in: die verbleibenden Sekunden bis zum Ablauf des Refresh-Tokens.
  • open_id: die anwendungsspezifische ID des TikTok-Kontos.
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>"
  }
}

Wie wird das Token bei API-Aufrufen gesendet?

Im Header der Anfrage mit dem Namen Access-Token, bei Accounts-API-Endpoints von /business/get/ bis /business/video/publish/. Das Konto selbst wird in business_id benannt, gesetzt auf die open_id aus derselben Antwort. Die OAuth-Endpoints funktionieren umgekehrt: /tt_user/oauth2/token/, /tt_user/oauth2/refresh_token/ und /tt_user/oauth2/revoke/ erhalten client_id und client_secret der App im JSON-Body und keinen Access-Token-Header.

Wie erneuern Sie das Access-Token?

Mit einem POST an /tt_user/oauth2/refresh_token/, der client_id, client_secret, grant_type mit dem Wert refresh_token und das gespeicherte refresh_token enthält. Die Antwort hat dieselben Felder wie der erste Austausch: ein neues access_token mit seinem expires_in, ein refresh_token für die nächste Erneuerung und die Sekunden, die es noch gültig ist. Planen Sie die Erneuerung vor Ablauf der 24 Stunden ein, statt auf Fehler 40102 zu warten.

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"],
    }

Wie widerrufen Sie den Zugriff?

Aus der App heraus mit einem POST an /tt_user/oauth2/revoke/, der client_id, client_secret und das zu widerrufende access_token enthält; bei Erfolg kommt code 0 mit einem leeren data-Objekt zurück. Vom Konto aus öffnet der Inhaber die TikTok-App, geht zu Settings and privacy, Security, Manage app permissions, wählt die App und klickt auf Remove access. Sobald die Autorisierung widerrufen ist, sendet TikTok der App für dieses Konto keine comment.update-Events mehr.

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

Wie prüfen Sie ein Token?

Mit einem POST an /tt_user/token_info/get/, der keine eigene Berechtigung braucht: senden Sie app_id und das access_token, und data liefert app_id, scope und creator_id zurück. scope listet auf, was der Inhaber gewährt hat, und creator_id ist die anwendungsspezifische ID des Kontos, also der Wert, den Accounts-API-Aufrufe als business_id verlangen. Die Referenzen von TikTok schicken Entwickler hierher, wenn ein Feld einen Scope braucht, den das Token möglicherweise nicht hat.

Welche Fehler kommen von Tokens?

TikTok legt sie im Feld code der Antwort ab, meist bei HTTP-Status 200, prüfen Sie daher code, bevor Sie einem Aufruf vertrauen. Die Rückgabecodes zu Tokens und deren Austausch:

  • 40102: das Access-Token ist abgelaufen; erneuern Sie es und rufen Sie erneut auf.
  • 40103: das Refresh-Token ist abgelaufen; nur eine neue Autorisierung durch den Inhaber ersetzt es.
  • 40104: die Anfrage enthielt kein Access-Token.
  • 40105: das Access-Token ist ungültig oder fehlerhaft.
  • 40107: das Refresh-Token ist ungültig oder fehlerhaft, zum Beispiel wenn es zur Erneuerung eines Marketing-API-Tokens gesendet wurde, das nie abläuft.
  • 40110: der Autorisierungscode wurde abgebrochen, bereits verwendet oder ist abgelaufen.
  • 40131: ein Authentifizierungsfehler an den beiden Token-Endpoints, durch eine falsche App-ID oder ein falsches Secret, einen abgelaufenen Code oder ein ungültiges oder abgelaufenes Refresh-Token.

Was erneuert easyCoexistence für Sie?

Alles nach der Anmeldung. easyCoexistence tauscht den Code, sobald TikTok zurückleitet, speichert beide Tokens verschlüsselt und erneuert das Access-Token selbst: vor einem Aufruf, wenn weniger als 15 Minuten übrig sind, und bei der Prüfung, die jedes Konto etwa alle 6 Stunden durchläuft, wenn weniger als 8 Stunden übrig sind. Jede Erneuerung speichert das neue Refresh-Token und dessen Ablauf, und gleichzeitig eintreffende Aufrufe teilen sich eine Erneuerung.

  • Abgelehntes Token: Antwortet TikTok mit 40102, 40104 oder 40105, wird die Verbindung zum Neuverbinden markiert und der Inhaber erhält eine E-Mail; Partner-API-Nutzer erhalten zusätzlich channel.disconnected.
  • Ihr eigener Code: get_social_credentials oder GET /channels/{id}?credentials=1 in der Partner API liefert das aktuelle Token mit token_expires_at, daher holen Sie es pro Job ab.
  • Entfernen: Das Entfernen der Verbindung im Dashboard oder mit DELETE /channels/{id} widerruft das Token bei TikTok über /tt_user/oauth2/revoke/.

Häufige Fehler

  • Den Autorisierungscode im Browser austauschen. Der Austausch sendet das client_secret der App, also führen Sie ihn auf Ihrem Server aus, innerhalb von 10 Minuten nach der Weiterleitung.
  • expires_in als Datum lesen. Der Wert enthält die verbleibenden Sekunden; addieren Sie ihn zur Zeit der Antwort, um den Ablauf des Tokens zu ermitteln.
  • Mit dem Refresh-Token widerrufen. /tt_user/oauth2/revoke/ verlangt das access_token zusammen mit client_id und client_secret der App.
  • Ein fehlendes Zustimmungsfenster als Fehler werten. TikTok überspringt die Prüfseite für Berechtigungen, die der Inhaber schon genehmigt hat; hängen Sie disable_auto_auth=1 an, um sie erneut anzuzeigen.
Mit EasyCoexistence

So rufen Claude, ChatGPT oder Ihr eigener Code TikTok mit einem aktuellen Token auf, das get_social_credentials an Ihre Skripte übergibt. US$ 9 bis US$ 0.75 pro Verbindung und Monat, sinkend mit jeder weiteren Verbindung, mit den ersten 3 Tagen als kostenlose Testphase.

Häufig gestellte Fragen

Wie lange gilt ein Access-Token der TikTok API for Business?

24 Stunden. Jede Token-Antwort nennt die verbleibenden Sekunden in expires_in, und das Refresh-Token, das ein Jahr gültig ist, erneuert es.

Braucht der TikTok-Refresh-Endpoint redirect_uri?

Die Parametertabelle nennt client_id, client_secret, grant_type und refresh_token, ohne redirect_uri, obwohl der Authentifizierungsleitfaden von TikTok sagt, dass seine Token-Endpoints redirect_uri verlangen.

Stoppt der Widerruf eines TikTok-Tokens dessen Webhooks?

Ja. TikTok sendet der App für dieses Konto keine comment.update-Events mehr, bis der Inhaber die App erneut autorisiert.

Woher kommt die business_id bei TikTok?

Aus open_id in der Token-Antwort, die Accounts-API-Aufrufe als business_id verwenden. /tt_user/token_info/get/ liefert dieselbe ID als creator_id.

Weiterlesen

Verbinden Sie Ihren ersten Kanal in zwei Minuten.

Keine Plattform-Prüfungen, auf die Sie warten müssen. Verbinden Sie WhatsApp, Instagram, TikTok oder einen anderen Kanal, bitten Sie dann Ihre KI, zu posten, zu antworten oder Berichte zu erstellen, und sehen Sie ihr bei der Arbeit zu.

  • 3 Tage kostenlos
  • Jederzeit kündbar
  • Nur offizielle APIs
  • Überwacht rund um die Uhr (24/7)

Verifiziert am