TikTok API for Business 存取權杖:24 小時、更新與撤銷
TikTok API for Business 存取權杖有效期為 24 小時,透過 Access-Token 標頭傳送。應用程式會以帳戶擁有者的授權碼,在 /tt_user/oauth2/token/ 交換取得權杖,同時取得有效期一年的刷新權杖,用以在 /tt_user/oauth2/refresh_token/ 更新存取權限。撤銷時使用 /tt_user/oauth2/revoke/,查閱已授予的權限範圍則使用 /tt_user/token_info/get/。
登入 TikTok 帳戶時,easyCoexistence 交換授權碼,在 24 小時權杖到期前更新,並約每 6 小時檢查一次帳戶,讓 Claude、ChatGPT 或你自己的程式都以有效的權杖呼叫 TikTok;get_social_credentials 會把權杖交給你的腳本。
TikTok 帳戶存取權杖的有效期;每個權杖回應都會以 expires_in 列出剩餘秒數。
隨之發出的刷新權杖的有效期;refresh_token_expires_in 會列出其剩餘秒數。
重定向中授權碼的有效時間;只能交換一次。
帳戶的應用程式專用 ID,隨每個權杖一併返回,並在 Accounts API 呼叫中以 business_id 傳送。
TikTok 返回的 token_type:持有權杖的人即可存取該帳戶的資源。
/tt_user/token_info/get/ 返回的帳戶 ID,與權杖的權限範圍一併提供,可在 Accounts API 呼叫中用作 business_id。
授權碼如何送達你的應用程式?
經由 TikTok 帳戶持有人授權網址。開發者在 My Apps、App Detail、Basic Information 中為應用程式建立此網址,前提是應用程式已取得 TikTok Accounts 權限。帳戶擁有者開啟網址、檢視權限並批准後,TikTok 會將瀏覽器導向應用程式的重定向網址,並附上 auth_code,以及授權網址中帶有的任何 state 值。該授權碼有效 10 分鐘,且只能交換一次。
- 重定向網址:必須為絕對網址,以 https:// 開頭、以 / 結尾,不含查詢字串、錨點或連接埠,長度為 10 至 512 個字元。
- 每個應用程式最多 10 個重定向網址,同一時間只能啟用一個;啟用後會產生其專屬的授權網址。
- state:選填值,TikTok 會在重定向時原樣返回,建議用作防範 CSRF 的保護。
disable_auto_auth=1:向之前已批准相同權限的擁有者顯示審閱頁面;否則 TikTok 會立即重定向他們。
如何將授權碼交換為權杖?
從你的伺服器以 JSON 格式向 /tt_user/oauth2/token/ 發出 POST 請求。client_id 與 client_secret 即 My Apps、App Detail、Basic Information 中顯示的 App ID 與 Secret;grant_type 為 authorization_code;auth_code 為重定向中的授權碼;redirect_uri 必須與應用程式中設定的 TikTok 帳戶持有人重定向網址完全相同。
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/"
}'權杖回應包含哪些內容?
一個 JSON 物件,包含 code、message、request_id 與 data。code 為 0 表示交換成功;data 內載有兩個權杖及帳戶 ID:
access_token:用於 API 呼叫的短期權杖,有效期一天。token_type:Bearer,TikTok 說明任何持有權杖的人均可使用。- scope:授予權杖的權限,以逗號分隔的單一字串表示。
expires_in:存取權杖剩餘的有效秒數,TikTok 範例中為 86400。refresh_token:用於更新存取權限的權杖,有效期一年;TikTok 建議妥善保存。refresh_token_expires_in:刷新權杖剩餘的有效秒數。open_id:TikTok 帳戶的應用程式專用 ID。
{
"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>"
}
}API 呼叫時如何傳送權杖?
在名為 Access-Token 的請求標頭中傳送,適用於由 /business/get/ 至 /business/video/publish/ 的 Accounts API 端點;帳戶本身則以 business_id 指定,其值為同一回應中的 open_id。OAuth 端點的做法則相反:/tt_user/oauth2/token/、/tt_user/oauth2/refresh_token/ 與 /tt_user/oauth2/revoke/ 須以 JSON 主體傳送應用程式的 client_id 與 client_secret,且不使用 Access-Token 標頭。
如何更新存取權杖?
向 /tt_user/oauth2/refresh_token/ 發出 POST 請求,帶上 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;成功時返回 code 0 與空的 data 物件。由帳戶端,擁有者開啟 TikTok 應用程式,前往「設定和私隱」、「安全」、「管理應用程式權限」,選擇該應用程式並點擊「移除存取權限」。權限一經撤銷,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": {}}如何檢查權杖?
以 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 的參考文件在某欄位需要權杖可能缺少的權限範圍時,都會引導開發者使用此端點。
權杖會產生哪些錯誤?
TikTok 會將錯誤放在回應的 code 欄位中,通常以 HTTP 狀態碼 200 返回,因此在信任呼叫結果之前,務必先檢查 code。與權杖及其交換相關的返回代碼如下:
- 40102:存取權杖已過期;請更新後重新呼叫。
- 40103:刷新權杖已過期;只有擁有者重新授權才能取代。
- 40104:請求未附帶存取權杖。
- 40105:存取權杖無效或不正確。
- 40107:刷新權杖無效或不正確,例如用來更新 Marketing API 權杖的刷新權杖,而該類權杖永不過期。
- 40110:授權碼已被取消、已被使用或已過期。
- 40131:兩個權杖端點出現的驗證錯誤,原因可能是 App ID 或 Secret 錯誤、授權碼已過期,或刷新權杖無效或已過期。
easyCoexistence 為你更新什麼?
登入之後的一切由 easyCoexistence 負責。TikTok 重定向回來後,easyCoexistence 即時交換授權碼,以加密方式儲存兩個權杖,並自行更新存取權杖:剩餘不足 15 分鐘時在呼叫前更新;每約 6 小時在各帳戶上執行的檢查中,若剩餘時間不足 8 小時,亦會更新。每次更新都會儲存新的刷新權杖及其到期時間,同時到達的呼叫會共用同一次更新。
- 權杖被拒:當 TikTok 返回 40102、40104 或 40105,該連接會被標示為需要重新連接,帳戶擁有者會收到電郵;Partner API 用戶亦會收到 channel.disconnected。
- 你自己的程式:
get_social_credentials,或在 Partner API 上的 GET /channels/{id}?credentials=1,會返回目前的權杖及token_expires_at,因此應在每項工作中分別取得。 - 移除:在控制台移除連接,或使用 DELETE /channels/{id},會透過 /
tt_user/oauth2/revoke/ 在 TikTok 端撤銷權杖。
常見錯誤
- 在瀏覽器中交換授權碼。交換過程會傳送應用程式的 client_secret,因此必須在伺服器端進行,且須在重定向後 10 分鐘內完成。
- 把 expires_in 當作日期。它代表剩餘秒數,應加上回應的時間,才能得知權杖的到期時間。
- 以刷新權杖撤銷。/tt_user/oauth2/revoke/ 須使用 access_token,並同時提供應用程式的 client_id 與 client_secret。
- 把缺少同意畫面視為失敗。對於擁有者之前已批准的權限,TikTok 會略過審閱頁面;如需再次顯示,請加上 disable_auto_auth=1。
每個連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,前 3 天免費試用。
常見問題
TikTok API for Business 存取權杖的有效期多久?
24 小時。每個權杖回應都會以 expires_in 列出剩餘秒數;有效期一年的刷新權杖可用來更新。
TikTok 的更新端點需要 redirect_uri 嗎?
其參數表列出 client_id、client_secret、grant_type 與 refresh_token,沒有 redirect_uri;不過 TikTok 的驗證指南指出其權杖端點需要 redirect_uri。
撤銷 TikTok 權杖後,其 Webhook 會停止嗎?
會。在擁有者重新授權應用程式之前,TikTok 不會再為該帳戶向應用程式發送 comment.update 事件。
TikTok 的 business_id 從哪裡來?
來自權杖回應中的 open_id,Accounts API 呼叫以此作為 business_id。/tt_user/token_info/get/ 會以 creator_id 返回相同的 ID。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期