登录开始免费试用
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/。

easyCoexistence 在 TikTok 账户登录时兑换授权码,在 24 小时访问令牌到期前续期,并约每 6 小时检查一次账户。

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 账户持有者授权 URL 传递。该 URL 由 TikTok 为开发者应用生成,位置在 My Apps、App Detail、Basic Information 中,前提是应用已获得 TikTok Accounts 权限。账户所有者打开该 URL,查看并批准权限。随后 TikTok 将浏览器跳转至应用的重定向 URL,并附上 auth_code;若授权 URL 带有 state,也会一并返回。该授权码有效期为 10 分钟,且只能兑换一次。

  • 重定向 URL:绝对地址,以 https:// 开头,以 / 结尾,不含查询字符串、锚点或端口,长度为 10 至 512 个字符。
  • 每个应用最多 10 个重定向 URL,同一时间仅一个处于启用状态;启用某个 URL 会生成对应的授权 URL。
  • state:可选参数,TikTok 会在重定向时原样返回,建议用于防范 CSRF 攻击。
  • disable_auto_auth=1:向此前已批准相同权限的所有者显示授权审核页面;否则 TikTok 会直接跳转。

如何用授权码换取令牌?

从您的服务器发送 POST 请求至 /tt_user/oauth2/token/,请求体为 JSON。client_id 和 client_secret 分别为 My Apps、App Detail、Basic Information 中显示的 App ID 与 Secret;grant_type 设为 authorization_code;auth_code 为重定向中的授权码;redirect_uri 必须与应用中设置的 TikTok 账户持有者重定向 URL 完全一致。

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

如何撤销访问权限?

在应用端,向 /tt_user/oauth2/revoke/ 发送 POST 请求,携带 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": {}}

如何检查令牌?

向 /tt_user/token_info/get/ 发送 POST 请求,无需任何额外权限:传入 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 或密钥错误、授权码过期,或刷新令牌无效或已过期。

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 完成这些操作

因此 Claude、ChatGPT 或您自己的代码调用 TikTok 时,使用的都是最新的访问令牌,get_social_credentials 会将其交给您的脚本。每个连接每月 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 监控

验证时间