TikTok API for Business : tokens d'accès de 24 heures, renouvellement et révocation
Un token d'accès de l'API for Business de TikTok dure 24 heures et s'envoie dans l'en-tête Access-Token. Une application l'obtient en échangeant le code d'autorisation du titulaire du compte à /tt_user/oauth2/token/, accompagné d'un token de rafraîchissement valable un an, qui sert à renouveler l'accès à /tt_user/oauth2/refresh_token/. Pour le révoquer, utilisez /tt_user/oauth2/revoke/ ; pour consulter les permissions accordées, /tt_user/token_info/get/.
easyCoexistence échange le code dès qu'un compte TikTok se connecte, renouvelle le token de 24 heures avant son expiration et contrôle le compte environ toutes les 6 heures, afin que Claude, ChatGPT ou votre propre code appelle TikTok avec un token à jour, que get_social_credentials remet à vos scripts.
Durée de vie d'un token d'accès de compte TikTok ; chaque réponse indique les secondes restantes dans expires_in.
Validité du token de rafraîchissement délivré avec lui ; refresh_token_expires_in donne ses secondes restantes.
Durée de validité du code d'autorisation dans la redirection ; il ne peut être échangé qu'une seule fois.
L'identifiant propre à l'application du compte, renvoyé avec chaque token et envoyé comme business_id dans les appels de l'Accounts API.
Le token_type renvoyé par TikTok : quiconque détient le token peut s'en servir pour accéder aux ressources du compte.
L'ID du compte renvoyé par /tt_user/token_info/get/ avec les permissions du token, utilisable comme business_id dans les appels de l'Accounts API.
Comment le code d'autorisation arrive-t-il dans votre application ?
Par l'URL d'autorisation du titulaire du compte TikTok, que TikTok génère pour une application développeur dans Mes apps, puis Détail de l'application, Informations de base, une fois que l'application détient l'autorisation TikTok Accounts. Le titulaire l'ouvre, examine les permissions et les approuve. TikTok renvoie alors le navigateur vers l'URL de redirection de l'application, avec un auth_code ajouté ainsi que la valeur state éventuelle portée par l'URL d'autorisation. Ce code est valable 10 minutes et ne sert qu'à un seul échange.
- URL de redirection : absolue, commençant par https://, se terminant par /, sans chaîne de requête, ancre ni port, et longue de 10 à 512 caractères.
- Jusqu'à 10 URL de redirection par application, une seule active à la fois ; l'activation de l'une génère sa propre URL d'autorisation.
- state : valeur facultative que TikTok renvoie lors de la redirection, qu'il suggère comme protection contre les attaques CSRF.
disable_auto_auth=1 : affiche la page de vérification aux titulaires ayant déjà approuvé les mêmes permissions, que TikTok redirige sinon immédiatement.
Comment échanger le code contre des tokens ?
Par un POST vers /tt_user/oauth2/token/ depuis votre serveur, au format JSON. client_id et client_secret correspondent à l'App ID et au Secret affichés dans Mes apps, Détail de l'application, Informations de base ; grant_type vaut authorization_code ; auth_code est le code reçu lors de la redirection ; et redirect_uri doit être identique à l'URL de redirection du titulaire du compte définie dans l'application.
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/"
}'Que contient la réponse renvoyée par TikTok ?
Un objet JSON avec code, message, request_id et data. Un code à 0 signifie que l'échange a réussi, et data contient les deux tokens ainsi que l'ID du compte :
access_token: le token d'accès court pour les appels à l'API, valable un jour.token_type: Bearer, que TikTok décrit comme utilisable par quiconque détient le token.- scope : les permissions accordées au token, sous forme d'une chaîne séparée par des virgules.
expires_in: les secondes restantes avant l'expiration de l'access_token, soit 86400 dans l'exemple de TikTok.refresh_token: le token qui renouvelle l'accès, valable un an ; TikTok recommande de le conserver.refresh_token_expires_in: les secondes restantes avant l'expiration durefresh_token.open_id: l'identifiant propre à l'application du compte 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>"
}
}Comment le token est-il envoyé lors des appels ?
Dans un en-tête de requête nommé Access-Token, sur les endpoints de l'Accounts API allant de /business/get/ à /business/video/publish/, tandis que le compte est désigné dans business_id, fixé à l'open_id de la même réponse. Les endpoints OAuth fonctionnent à l'inverse : /tt_user/oauth2/token/, /tt_user/oauth2/refresh_token/ et /tt_user/oauth2/revoke/ prennent client_id et client_secret de l'application dans un corps JSON, sans en-tête Access-Token.
Comment renouveler le token d'accès ?
Par un POST vers /tt_user/oauth2/refresh_token/ contenant client_id, client_secret, grant_type égal à refresh_token et le refresh_token conservé. La réponse comporte les mêmes champs que le premier échange : un nouvel access_token avec son expires_in, un refresh_token à conserver pour le prochain renouvellement et les secondes qui lui restent. Planifiez le renouvellement avant les 24 heures plutôt que d'attendre l'erreur 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"],
}Comment révoquer l'accès ?
Depuis l'application, par un POST vers /tt_user/oauth2/revoke/ contenant client_id, client_secret et l'access_token à révoquer ; en cas de succès, la réponse renvoie code 0 avec un objet data vide. Depuis le compte, le titulaire ouvre l'application TikTok, va dans Paramètres et confidentialité, Sécurité, Gérer les autorisations des applications, choisit l'application puis Supprimer l'accès. Une fois l'autorisation révoquée, TikTok cesse d'envoyer à l'application les événements comment.update pour ce compte.
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": {}}Comment inspecter un token ?
Par un POST vers /tt_user/token_info/get/, qui ne nécessite aucune permission propre : envoyez app_id et l'access_token, et data renvoie app_id, scope et creator_id. scope liste ce que le titulaire a accordé, et creator_id est l'identifiant propre au compte, la valeur que les appels de l'Accounts API prennent comme business_id. Les références de TikTok renvoient les développeurs ici chaque fois qu'un champ exige une permission que le token pourrait ne pas avoir.
Quelles erreurs proviennent des tokens ?
TikTok les place dans le champ code de la réponse, généralement avec le statut HTTP 200, donc vérifiez code avant de considérer un appel comme réussi. Les codes de retour liés aux tokens et à leur échange :
- 40102 : le token d'accès a expiré ; renouvelez-le puis relancez l'appel.
- 40103 : le
refresh_tokena expiré ; seule une nouvelle autorisation du titulaire le remplace. - 40104 : la requête ne contenait aucun token d'accès.
- 40105 : le token d'accès est invalide ou incorrect.
- 40107 : le
refresh_tokenest invalide ou incorrect, par exemple celui envoyé pour renouveler un token de la Marketing API, qui n'expire jamais. - 40110 : le code d'autorisation a été annulé, déjà utilisé ou a expiré.
- 40131 : une erreur d'authentification sur les deux endpoints de token, due à un App ID ou un secret erroné, à un code expiré, ou à un
refresh_tokeninvalide ou expiré.
Que renouvelle easyCoexistence pour vous ?
Tout ce qui suit la connexion. easyCoexistence échange le code dès que TikTok redirige, stocke les deux tokens chiffrés et renouvelle lui-même le token d'accès : avant un appel lorsqu'il reste moins de 15 minutes, et lors de la vérification qu'il effectue sur chaque compte environ toutes les 6 heures lorsqu'il reste moins de 8 heures. Chaque renouvellement enregistre le nouveau refresh_token et son échéance, et les appels arrivant ensemble partagent un seul renouvellement.
- Token rejeté : lorsque TikTok répond 40102, 40104 ou 40105, la connexion est marquée pour une reconnexion et le titulaire reçoit un e-mail ; les utilisateurs de la Partner API reçoivent aussi channel.disconnected.
- Votre propre code :
get_social_credentials, ou GET /channels/{id}?credentials=1 sur la Partner API, renvoie le token actuel avectoken_expires_at; récupérez-le donc à chaque tâche. - Suppression : supprimer la connexion dans le dashboard, ou avec DELETE /channels/{id}, révoque le token chez TikTok via /
tt_user/oauth2/revoke/.
Erreurs courantes
- Échanger le code d'autorisation dans le navigateur. L'échange envoie le client_secret de l'application : effectuez-le depuis votre serveur, dans les 10 minutes suivant la redirection.
- Lire expires_in comme une date. Il contient les secondes restantes : ajoutez-le à l'heure de la réponse pour connaître l'échéance du token.
- Révoquer avec le refresh_token. /tt_user/oauth2/revoke/ prend l'access_token, avec le client_id et le client_secret de l'application.
- Considérer l'absence d'écran de consentement comme un échec. TikTok saute la page de vérification pour les permissions déjà approuvées par le titulaire ; ajoutez disable_auto_auth=1 pour l'afficher à nouveau.
De US$ 9 à US$ 0,75 par connexion et par mois, dégressif à mesure que vous ajoutez des connexions, avec un essai gratuit de 3 jours.
Questions fréquemment posées
Combien de temps dure un token d'accès TikTok API for Business ?
24 heures. Chaque réponse de TikTok indique les secondes restantes dans expires_in ; le token de rafraîchissement, valable un an, permet de le renouveler.
Le endpoint de renouvellement de TikTok a-t-il besoin de redirect_uri ?
Son tableau des paramètres liste client_id, client_secret, grant_type et refresh_token, sans redirect_uri, alors que le guide d'authentification de TikTok indique que ses endpoints de token exigent redirect_uri.
La révocation d'un token TikTok arrête-t-elle ses webhooks ?
Oui. TikTok n'envoie plus à l'application les événements comment.update de ce compte tant que le titulaire n'a pas à nouveau autorisé l'application.
D'où vient le business_id de TikTok ?
De open_id dans la réponse du token, que les appels de l'Accounts API prennent comme business_id. /tt_user/token_info/get/ renvoie le même identifiant sous le nom creator_id.
Poursuivre la lecture
Connectez votre premier canal en deux minutes.
Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.
- 3 jours gratuits
- Résiliable à tout moment
- API officielles uniquement
- Supervisé 24/7
Vérifié le