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 小时检查一次账户。
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 账户持有者授权 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 完全一致。
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"],
}如何撤销访问权限?
在应用端,向 /tt_user/oauth2/revoke/ 发送 POST 请求,携带 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": {}}如何检查令牌?
向 /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 即可重新显示。
因此 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 监控
验证时间