TikTok Video Auth

TikTok 达人体系授权与管理技能，经 /tiktokVideo 路由提供达人/视频号 OAuth 授权、已授权账号列表、令牌查询与 access_token 刷新。固定 creator 达人端，region 支持 global / us。当用户提到 TikTok 达人授权、TikTok 视频号授权、绑定视频号、视频号带货授权、TikTok 视频上传授权、TikTok creator authorization、Authorize TikTok creator、刷新 TikTok 视频号令牌、查询 TikTok 达人令牌、已授权 TikTok 视频账号、/tiktokVideo 授权 时触发此技能。只要需求涉及达人/视频号账号授权或访问令牌管理，也应触发。**不要**使用 linkfox-tiktok-auth（/tiktokShop）做达人授权。

TikTok 视频上传 API — 授权与管理

本 skill 负责 TikTok 视频上传模块（/tiktokVideo） 的达人 OAuth 授权、已授权账号列表、令牌查询与刷新，是后续通过 /tiktokVideo/developerProxy 调用视频上传等开放接口的前置依赖。底层经 LinkFox 网关对接紫鸟开放平台，固定 appType=creator（达人端带货 / 视频上传）。

📌 模块边界

• 本 skill（/tiktokVideo）：达人体系授权的唯一入口 — 视频号 OAuth、令牌管理，独立数据表，无需传 appType。
• linkfox-tiktok-auth（/tiktokShop）：仅 TikTok Shop 卖家授权（erp / affiliate），不处理达人/视频号授权。
• 两者授权数据不互通；业务调用须使用对应模块取得的 accessToken。

📌 视频上传等业务调用通过 /tiktokVideo/developerProxy（传入本 skill 取得的 accessToken 作为 ttsAccessToken）完成，由 linkfox-tiktok-video 负责。

Core Concepts

授权流程：调用 /tiktokVideo/authorizeUrl 生成授权 URL → 用户在浏览器完成达人授权 → 紫鸟 POST Token 到 /tiktokVideo/oauth/tokenCallback（messageType=251）→ 系统按 state 落库。授权 URL 有效期约 1 小时，每次授权须重新获取。

账号标识（openId）：授权后以创作者唯一标识 openId 标记账号。查询令牌、刷新令牌均只需 openId（无需 appType）。

令牌生命周期：accessToken 与 refreshToken 均带绝对过期时间（Unix 时间戳）。accessToken 过期用 refreshToken 续签；refreshToken 过期须重新走授权流程。

Data Fields

Authorization URL Response

Field	Type	Description
authorizeUrl	string	让用户在浏览器打开的达人授权链接（有效期约 1 小时）

Authorized Account Item

Field	Type	Description
openId	string	创作者 open_id
displayName	string	展示名称
region	string	授权 region：global / us
userType	integer	用户类型（如 1=创作者）
grantedScopes	string	已授权 scope 列表 JSON

Account Tokens

Field	Type	Description
accessToken	string	调用 /tiktokVideo/developerProxy 的凭证（作为 ttsAccessToken）
refreshToken	string	用于续签 accessToken
accessTokenExpireIn	integer	accessToken 过期 Unix 时间戳
refreshTokenExpireIn	integer	refreshToken 过期 Unix 时间戳
userType	integer	用户类型
grantedScopes	string	已授权 scope 列表 JSON

Supported Regions

region	说明
global	全球（默认）
us	美国站

API Usage

本 skill 经 LinkFox 网关调用 TikTok 视频上传授权相关接口。入参枚举、响应嵌套字段与错误码详见 references/api.md（含 accounts[] 元素字段、accountTokens 完整出参）。

Available Scripts

• scripts/authorize_url.py — 生成达人授权 URL（可选 displayName / region）
• scripts/authorized_accounts.py — 列出当前用户已授权的视频号
• scripts/account_tokens.py — 按 openId 查询已入库令牌（供下游业务使用）
• scripts/refresh_token.py — 刷新某账号的 access_token

Usage Scenarios

Scenario 1: Authorize New Creator Account

User request：「我要授权 TikTok 视频上传 / 绑定视频号用于上传视频」

Steps：

1. 确认 region（美国站用 us，否则默认 global）。可选询问 displayName 作为展示标签。
2. 调用 /tiktokVideo/authorizeUrl，得到 authorizeUrl。
3. 把 authorizeUrl 给用户，让其在浏览器中打开并完成授权（链接约 1 小时失效）。
4. 用户完成授权 → 紫鸟回调推送 Token → 系统自动落库。
5. 可选：调用 /tiktokVideo/authorizedAccounts 确认授权成功。

Scenario 2: View Authorized Accounts

User request：「列一下我已授权的 TikTok 视频号」

Steps：

1. 调用 /tiktokVideo/authorizedAccounts。
2. 展示账号列表（displayName / openId / region / userType）。

Scenario 3: Refresh Expired Token

User request：「我 TikTok 视频上传的令牌过期了，帮我刷新」

Steps：

1. 调用 /tiktokVideo/refreshToken，传入 openId。
2. 返回新的 accessToken / refreshToken 并回写数据库。
3. 若 refreshToken 已过期，引导用户重新走 Scenario 1 授权。

Scenario 4: Query Account Tokens

User request：「获取某 TikTok 视频号的访问令牌」

Steps：

1. 调用 /tiktokVideo/accountTokens，传入 openId。
2. 返回令牌信息（供下游 /tiktokVideo/developerProxy 使用）。

Scenario 5: Prepare Token for Video Upload (Standard Preparation Workflow)

当用户提出涉及 TikTok 视频上传的请求，本 skill 负责前置的「选号 → 取令牌」流程，业务由 /tiktokVideo/developerProxy 接手。

Steps：

1. 列出已授权账号：调用 /tiktokVideo/authorizedAccounts。
2. 让用户选择账号：多个视频号时请用户明确选择。
3. 获取该账号令牌：调用 /tiktokVideo/accountTokens，传入 openId。
4. 把 accessToken 作为 ttsAccessToken 交给 /tiktokVideo/developerProxy 执行具体业务调用。

Display Rules

1. 只呈现数据：展示授权结果、账号列表、令牌信息即可，不做业务建议。
2. 安全意识：不要明文显示完整 accessToken / refreshToken，仅展示前 10 字符等掩码形式。
3. 清晰引导：返回授权链接时，明确告知用户在浏览器中打开并完成授权，且链接约 1 小时失效。
4. 过期解读：accessTokenExpireIn / refreshTokenExpireIn 为绝对 Unix 时间戳，需与当前时间比较判断是否过期。
5. 错误说明：授权或刷新失败时，基于错误码解释原因并给出建议。

Important Limitations

• 模块独立：本 skill 令牌仅适用于 /tiktokVideo/*，不可用于 /tiktokShop/developerProxy。
• 令牌有效期：accessToken 较短，过期需用 refreshToken 续签；refreshToken 过期须重新授权。
• 授权链接时效：authorizeUrl 有效期约 1 小时，过期需重新获取。
• 用户隔离：用户只能查看/管理自己授权的账号。
• 回调白名单：系统回调 URL 与调用 IP 必须在授权方（紫鸟）处加白名单。

User Expression & Scenario Quick Reference

Applicable — 授权与令牌管理场景：

User Says	Scenario
"授权 TikTok 视频上传" / "Authorize TikTok video upload account"	新视频号授权
"绑定 TikTok 视频号用于上传视频"	新视频号授权
"看看已授权的 TikTok 视频号" / "Show my authorized TikTok video accounts"	列出已授权账号
"TikTok 视频上传令牌过期了" / "My TikTok video token expired"	刷新令牌
"获取 TikTok 视频号的访问令牌" / "Get TikTok video account access token"	查询账号令牌

Not applicable — 超出本 skill 的业务：

• TikTok Shop 小店授权（appType=erp）→ 用 linkfox-tiktok-auth
• TikTok Shop 可购物视频 / affiliate_creator 达人接口 → 用 linkfox-tiktok-creator（业务 skill；授权仍走本 skill）
• TikTok 视频上传具体业务（上传、发布等）→ 用 linkfox-tiktok-video（经 /tiktokVideo/developerProxy）
• TikTok 选品 / 达人带货数据分析 → 由 EchoTik 等其他 skill 负责

Boundary judgment：

• 本 skill 只负责「授权 + 管账号 + 管令牌 + 为下游准备 accessToken」。
• 当用户要做视频上传等具体业务时：先执行 Scenario 5 的标准前置流程，再由 /tiktokVideo/developerProxy 完成业务逻辑。

Quick Reference

Authorization & Token Management APIs

API	Path	Purpose	Auth Required
Get Authorization URL	/tiktokVideo/authorizeUrl	生成达人授权链接	✅ Yes
List Authorized Accounts	/tiktokVideo/authorizedAccounts	查询用户的视频号列表	✅ Yes
Query Account Tokens	/tiktokVideo/accountTokens	查询某账号已入库令牌	✅ Yes
Refresh Token	/tiktokVideo/refreshToken	刷新访问令牌	✅ Yes

详细请求参数、响应结构、错误码，见 references/api.md。

Feedback：

当出现以下任一情况时，自动通过 Feedback API 上报反馈：

1. 本 skill 描述的功能与实际行为不符
2. skill 的结果与用户意图不符
3. 用户表达了对本 skill 的不满或赞赏
4. 任何你认为可以改进的点

按 references/api.md 中的规范调用 Feedback API，不要打断用户的主流程。

---

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.