Tokens πρόσβασης του TikTok API for Business: 24 ώρες, ανανέωση και ανάκληση
Ένα token πρόσβασης του TikTok API for Business ισχύει 24 ώρες και ταξιδεύει στην κεφαλίδα Access-Token. Μια εφαρμογή το αποκτά ανταλλάσσοντας τον κωδικό εξουσιοδότησης του ιδιοκτήτη στο /tt_user/oauth2/token/, μαζί με ένα refresh token που ισχύει ένα χρόνο και ανανεώνει την πρόσβαση στο /tt_user/oauth2/refresh_token/. Η ανάκληση γίνεται στο /tt_user/oauth2/revoke/, ενώ τα εγκεκριμένα scopes εμφανίζονται στο /tt_user/token_info/get/.
Το easyCoexistence ανταλλάσσει τον κωδικό όταν ένας λογαριασμός TikTok συνδέεται, ανανεώνει το token των 24 ωρών πριν λήξει και ελέγχει τον λογαριασμό περίπου κάθε 6 ώρες, ώστε το Claude, το ChatGPT ή ο δικός σας κώδικας να καλεί το TikTok με ενεργό token, το οποίο το get_social_credentials παραδίδει στα scripts σας.
Η διάρκεια ενός token πρόσβασης λογαριασμού TikTok, με κάθε απάντηση να δηλώνει τα δευτερόλεπτα που απομένουν στο expires_in.
Η ισχύς του refresh token που εκδίδεται μαζί του, με το refresh_token_expires_in να δίνει τα δευτερόλεπτα που απομένουν.
Για πόσο ισχύει ο κωδικός εξουσιοδότησης στο redirect, ο οποίος μπορεί να ανταλλαγεί μόνο μία φορά.
Το ID της εφαρμογής για τον λογαριασμό, που επιστρέφεται με κάθε token και στέλνεται ως business_id στις κλήσεις του Accounts API.
Το token_type που επιστρέφει το TikTok: όποιος έχει το token μπορεί να φτάσει στους πόρους του λογαριασμού.
Το ID του λογαριασμού που επιστρέφει το /tt_user/token_info/get/ μαζί με το scope του token, και που μπορεί να χρησιμοποιηθεί ως business_id στις κλήσεις του Accounts API.
Πώς φτάνει ο κωδικός εξουσιοδότησης στην εφαρμογή σας;
Μέσω του URL εξουσιοδότησης του κατόχου λογαριασμού TikTok, το οποίο το TikTok δημιουργεί για μια εφαρμογή προγραμματιστή στο My Apps, App Detail, Basic Information, μόλις η εφαρμογή αποκτήσει το δικαίωμα TikTok Accounts. Ο ιδιοκτήτης του λογαριασμού το ανοίγει, ελέγχει τα δικαιώματα και τα εγκρίνει. Έπειτα το TikTok στέλνει το πρόγραμμα περιήγησης στο redirect URL της εφαρμογής, με προσθήκη ενός auth_code και της τιμής state, αν το URL εξουσιοδότησης την είχε. Ο κωδικός ισχύει 10 λεπτά και για μία μόνο ανταλλαγή.
- Redirect URL: απόλυτο, ξεκινά με https://, τελειώνει σε /, χωρίς query string, άγκυρα ή θύρα, και έχει μήκος 10 έως 512 χαρακτήρες.
- Έως 10 redirect URLs ανά εφαρμογή, με ένα ενεργό κάθε φορά. Η ενεργοποίηση ενός δημιουργεί το δικό του URL εξουσιοδότησης.
- state: προαιρετική τιμή που το TikTok επιστρέφει στο redirect, και που προτείνει ως δικλείδα προστασίας από CSRF.
disable_auto_auth=1: εμφανίζει τη σελίδα ελέγχου σε ιδιοκτήτες που είχαν ήδη δώσει έγκριση για τα ίδια δικαιώματα, και τους οποίους αλλιώς το TikTok ανακατευθύνει αμέσως.
Πώς ανταλλάσσετε τον κωδικό με tokens;
Με POST στο /tt_user/oauth2/token/ από τον διακομιστή σας, σε JSON. Τα client_id και client_secret είναι το App ID και το Secret που εμφανίζονται στο My Apps, App Detail, Basic Information. Το grant_type είναι authorization_code, το auth_code είναι ο κωδικός από το redirect, και το redirect_uri πρέπει να ταυτίζεται με το TikTok account holder redirect URL που έχει οριστεί στην εφαρμογή.
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/"
}'Τι περιέχει η απάντηση του token;
Ένα αντικείμενο JSON με code, message, request_id και data. Κωδικός 0 σημαίνει ότι η ανταλλαγή πέτυχε, και το data φέρει και τα δύο tokens και το ID του λογαριασμού:
access_token: το βραχυπρόθεσμο token για κλήσεις API, με ισχύ μίας ημέρας.token_type: Bearer, που το TikTok περιγράφει ως χρησιμοποιήσιμο από όποιον κατέχει το token.- scope: τα δικαιώματα που δόθηκαν στο token, σε μία συμβολοσειρά χωρισμένη με κόμματα.
expires_in: τα δευτερόλεπτα που απομένουν έως τη λήξη του access token, 86400 στο παράδειγμα του TikTok.refresh_token: το token που ανανεώνει την πρόσβαση, με ισχύ ενός έτους. Η σημείωση του TikTok είναι να το διατηρείτε.refresh_token_expires_in: τα δευτερόλεπτα που απομένουν έως τη λήξη του refresh token.open_id: το ID της εφαρμογής για τον λογαριασμό 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>"
}
}Πώς στέλνεται το token στις κλήσεις API;
Σε κεφαλίδα αιτήματος με όνομα Access-Token, στα endpoints του Accounts API από το /business/get/ έως το /business/video/publish/, ενώ ο λογαριασμός ορίζεται στο business_id, με τιμή το open_id της ίδιας απάντησης. Τα endpoints OAuth λειτουργούν αντίστροφα: τα /tt_user/oauth2/token/, /tt_user/oauth2/refresh_token/ και /tt_user/oauth2/revoke/ παίρνουν τα client_id και client_secret της εφαρμογής σε σώμα JSON, χωρίς κεφαλίδα Access-Token.
Πώς ανανεώνετε το access token;
Με POST στο /tt_user/oauth2/refresh_token/ που περιέχει client_id, client_secret, grant_type με τιμή refresh_token και το αποθηκευμένο refresh_token. Η απάντηση έχει τα ίδια πεδία με την πρώτη ανταλλαγή: ένα νέο access_token με το expires_in του, ένα refresh_token για την επόμενη ανανέωση και τα δευτερόλεπτα που του απομένουν. Προγραμματίστε την ανανέωση πριν από τις 24 ώρες, αντί να περιμένετε το σφάλμα 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"],
}Πώς ανακαλείτε την πρόσβαση;
Από την εφαρμογή, με POST στο /tt_user/oauth2/revoke/ που περιέχει client_id, client_secret και το access_token προς ανάκληση. Η επιτυχία επιστρέφει κωδικό 0 με κενό αντικείμενο data. Από τον λογαριασμό, ο ιδιοκτήτης ανοίγει την εφαρμογή TikTok, μεταβαίνει στο Settings and privacy, Security, Manage app permissions, επιλέγει την εφαρμογή και πατά Remove access. Μόλις ανακληθεί η εξουσιοδότηση, το TikTok σταματά να στέλνει στην εφαρμογή τα συμβάντα comment.update για τον λογαριασμό.
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": {}}Πώς ελέγχετε ένα token;
Με POST στο /tt_user/token_info/get/, για το οποίο δεν απαιτείται δικό του δικαίωμα. Στέλνετε το app_id και το access_token, και το data επιστρέφει app_id, scope και creator_id. Το scope απαριθμεί όσα έδωσε ο ιδιοκτήτης, ενώ το creator_id είναι το ID του λογαριασμού για την εφαρμογή, η τιμή που οι κλήσεις του Accounts API δέχονται ως business_id. Οι οδηγίες του TikTok παραπέμπουν εδώ κάθε φορά που ένα πεδίο χρειάζεται scope που μπορεί να λείπει από το token.
Ποια σφάλματα προέρχονται από τα tokens;
Το TikTok τα βάζει στο πεδίο code της απάντησης, συνήθως με HTTP κατάσταση 200, οπότε ελέγξτε το code πριν εμπιστευτείτε μια κλήση. Οι κωδικοί επιστροφής που σχετίζονται με τα tokens και την ανταλλαγή τους:
- 40102: το access token έχει λήξει. Ανανεώστε το και καλέστε ξανά.
- 40103: το refresh token έχει λήξει. Μόνο νέα εξουσιοδότηση από τον ιδιοκτήτη το αντικαθιστά.
- 40104: το αίτημα δεν περιείχε access token.
- 40105: το access token δεν είναι έγκυρο ή είναι λανθασμένο.
- 40107: το refresh token δεν είναι έγκυρο ή είναι λανθασμένο, για παράδειγμα όταν στέλνεται για ανανέωση token του Marketing API, το οποίο δεν λήγει ποτέ.
- 40110: ο κωδικός εξουσιοδότησης ακυρώθηκε, έχει ήδη χρησιμοποιηθεί ή έχει λήξει.
- 40131: σφάλμα ταυτοποίησης στα δύο endpoints των tokens, από λανθασμένο App ID ή secret, λήξη κωδικού, ή μη έγκυρο ή ληγμένο refresh token.
Τι ανανεώνει το easyCoexistence για εσάς;
Όλα όσα ακολουθούν τη σύνδεση. Το easyCoexistence ανταλλάσσει τον κωδικό μόλις το TikTok σας επιστρέψει, αποθηκεύει και τα δύο tokens κρυπτογραφημένα και ανανεώνει μόνο του το access token: πριν από μια κλήση, όταν απομένουν λιγότερα από 15 λεπτά, και κατά τον έλεγχο που τρέχει σε κάθε λογαριασμό περίπου κάθε 6 ώρες, όταν απομένουν λιγότερες από 8 ώρες. Κάθε ανανέωση αποθηκεύει το νέο refresh token και τη λήξη του, ενώ οι κλήσεις που φτάνουν μαζί μοιράζονται μία ανανέωση.
- Απορριφθέν token: όταν το TikTok απαντά 40102, 40104 ή 40105, η σύνδεση επισημαίνεται για επανασύνδεση και ο ιδιοκτήτης λαμβάνει email. Οι χρήστες του Partner API λαμβάνουν επιπλέον το channel.disconnected.
- Δικός σας κώδικας: το
get_social_credentials, ή το GET /channels/{id}?credentials=1 στο Partner API, επιστρέφει το τρέχον token με τοtoken_expires_at, γι' αυτό ζητήστε το ανά εργασία. - Αφαίρεση: η αφαίρεση της σύνδεσης στο dashboard, ή με DELETE /channels/{id}, ανακαλεί το token στο TikTok μέσω του /
tt_user/oauth2/revoke/.
Συνηθισμένα λάθη
- Ανταλλαγή του κωδικού εξουσιοδότησης στον browser. Η ανταλλαγή στέλνει το client_secret της εφαρμογής, οπότε κάντε την από τον διακομιστή σας, μέσα σε 10 λεπτά από το redirect.
- Ανάγνωση του expires_in ως ημερομηνίας. Περιέχει τα δευτερόλεπτα που απομένουν, οπότε προσθέστε τα στον χρόνο της απάντησης για να μάθετε πότε λήγει το token.
- Ανάκληση με το refresh token. Το /tt_user/oauth2/revoke/ δέχεται το access_token, μαζί με το client_id και το client_secret της εφαρμογής.
- Αντιμετώπιση της απουσίας οθόνης συναίνεσης ως αποτυχίας. Το TikTok παραλείπει τη σελίδα ελέγχου για δικαιώματα για τα οποία ο ιδιοκτήτης έχει ήδη δώσει έγκριση. Προσθέστε disable_auto_auth=1 για να την εμφανίσετε ξανά.
Από US$ 9 έως US$ 0.75 ανά σύνδεση τον μήνα, με πτώση καθώς προσθέτετε συνδέσεις, και με τις πρώτες 3 ημέρες δωρεάν.
Συχνές ερωτήσεις
Πόση είναι η διάρκεια ενός token πρόσβασης του TikTok API for Business;
24 ώρες. Κάθε απάντηση token δίνει τα δευτερόλεπτα που απομένουν στο expires_in, και το refresh token, με ισχύ ενός έτους, το ανανεώνει.
Χρειάζεται το endpoint ανανέωσης του TikTok το redirect_uri;
Ο πίνακας παραμέτρων του αναφέρει τα client_id, client_secret, grant_type και refresh_token, χωρίς redirect_uri. Ο οδηγός ταυτοποίησης του TikTok, ωστόσο, λέει ότι τα endpoints των tokens απαιτούν redirect_uri.
Σταματά η ανάκληση ενός token του TikTok τα webhooks του;
Ναι. Το TikTok δεν στέλνει πια στην εφαρμογή συμβάντα comment.update για τον λογαριασμό, μέχρι ο ιδιοκτήτης να εξουσιοδοτήσει ξανά την εφαρμογή.
Από πού προέρχεται το business_id του TikTok;
Από το open_id της απάντησης του token, το οποίο οι κλήσεις του Accounts API δέχονται ως business_id. Το /tt_user/token_info/get/ επιστρέφει το ίδιο ID ως creator_id.
Συνεχίστε την ανάγνωση
Συνδέστε το πρώτο σας κανάλι σε δύο λεπτά.
Χωρίς αναμονή για έλεγχο από τις πλατφόρμες. Συνδέστε WhatsApp, Instagram, TikTok ή άλλο κανάλι, ζητήστε από το AI σας να δημοσιεύσει, να απαντήσει ή να δημιουργήσει αναφορά και δείτε το να δουλεύει.
- 3 ημέρες δωρεάν
- Ακύρωση ανά πάσα στιγμή
- Μόνο επίσημα API
- Παρακολούθηση 24/7
Επαληθεύτηκε στις