登入開始免費試用
easyCoexistence 官方 API

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 會把權杖交給你的腳本。

24 hours

TikTok 帳戶存取權杖的有效期;每個權杖回應都會以 expires_in 列出剩餘秒數。

1 year

隨之發出的刷新權杖的有效期;refresh_token_expires_in 會列出其剩餘秒數。

10 minutes

重定向中授權碼的有效時間;只能交換一次。

open_id

帳戶的應用程式專用 ID,隨每個權杖一併返回,並在 Accounts API 呼叫中以 business_id 傳送。

Bearer

TikTok 返回的 token_type:持有權杖的人即可存取該帳戶的資源。

creator_id

/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 帳戶持有人重定向網址完全相同。

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

權杖回應包含哪些內容?

一個 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。
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>"
  }
}

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 才處理。

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

如何撤銷存取權限?

由應用程式端,以 POST 請求發送至 /tt_user/oauth2/revoke/,並帶上 client_id、client_secret,以及要撤銷的 access_token;成功時返回 code 0 與空的 data 物件。由帳戶端,擁有者開啟 TikTok 應用程式,前往「設定和私隱」、「安全」、「管理應用程式權限」,選擇該應用程式並點擊「移除存取權限」。權限一經撤銷,TikTok 便會停止為該帳戶向應用程式發送 comment.update 事件。

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

如何檢查權杖?

以 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。
使用 EasyCoexistence 完成這項設定

每個連接每月 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 監察

驗證日期