SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-tiktok-auth

linkfox-tiktok-auth

General & other

View repository

Updated 10-16 06:23

About this skill

TikTok Shop Shop Authorization and Management

This skill is responsible for OAuth authorization for TikTok seller accounts, the list of authorized shops, and token query and refresh, and is a prerequisite dependency for subsequently calling TikTok open APIs (products, orders, fulfillment, finance, etc.) through the developer proxy. At the underlying level, it connects to the Ziniao Open Platform proxy via the LinkFox gateway.

This skill covers two types of authorization at the same time, distinguished by appType :

  • TikTok Shop (store) authorization：appType = erp(default).
  • TikTok video account (shoppable content) authorization：appType = creator. When authorizing a video account,you mustset appType to creator; when subsequently querying/refreshing the token for that authorization, appType = creator。
  • Affiliate authorization:appType = affiliate。

📌 Business calls (pulling products/orders/finance, etc.) are completed through the developer proxy (/tiktokShop/developerProxy, passing in the accessTokenobtained by this skill),and are not within the scope of this authorization skill。

Core Concepts

TikTok Shop obtains seller shop access tokens through OAuth authorization. This skill is responsible for the authorization process and token lifecycle:

Authorization process: generate authorization URL → the user completes TikTok Shop authorization in the browser → Ziniao callback and pushes the Token → the system stores it in the database by state as access_token / refresh_token. The authorization URL is valid for about 1 hour, and must be obtained again for each authorization.

Shop identifier (openId + appType）: after TikTok Shop authorization, the shop is marked by the seller's unique identifier openId ; authorizations for the same shop under different appType（erp / creator / affiliate) are independent of each other. Querying tokens and refreshing tokens both require openId, and ensure that appType is consistent with that at the time of authorization.

Token lifecycle：accessToken and refreshToken both carry absolute expiration times (Unix timestamps).accessToken If expired, use refreshToken to renew;refreshToken if expired, the authorization process must be carried out again.

Data Fields

Authorization URL Response

Field Type Description
authorizeUrl string The TikTok Shop authorization link for the user to open in the browser (valid for about 1 hour)

Authorized Store Item

Field Type Description
openId string Seller unique identifier
sellerName string Shop name
sellerBaseRegion string Region where the shop is located (e.g. ID)
appType string Application type: erp / creator / affiliate
region string Authorization region: global / us

Store Tokens

Field Type Description
accessToken string Credential for calling TikTok Shop open APIs
refreshToken string Used to renew accessToken
accessTokenExpireIn integer accessToken expiration Unix timestamp
refreshTokenExpireIn integer refreshToken expiration Unix timestamp

Supported Regions & App Types

region Description
global Global (default)
us US site
appType Description
erp ERP application (default) — used for TikTok Shop store authorization
creator Shoppable content — used for TikTok video account authorization
affiliate Affiliate (must be consistent with authorization when refreshing the token)

To authorize a video account: when calling /tiktokShop/authorizeUrl , pass appType=creator; the shop for this authorization is in /tiktokShop/storeTokens、/tiktokShop/refreshToken must also be passed appType=creator, independent of the shop (erp) authorization.

API Usage

This skill calls TikTok Shop authorization-related APIs through the LinkFox gateway. See references/api.md。

Available Scripts

  • scripts/authorize_url.py — Generate TikTok Shop authorization URL (optional shopName / region / appType）
  • scripts/authorized_stores.py — List the shops the current user has authorized
  • scripts/store_tokens.py — By openId + appType query stored tokens (for downstream business use)
  • scripts/refresh_token.py — Refresh a shop's access_token

Usage Scenarios

Scenario 1: Authorize New Shop

User request: "I want to authorize my TikTok Shop US site"

Steps：

  1. Confirm region(for the US site use us, otherwise default global) and appType(default erp). Optionally ask for shopName as a display label.
  2. Call /tiktokShop/authorizeUrl, get authorizeUrl。
  3. Give authorizeUrl to the user, have them open it in a browser and complete authorization (the link expires in about 1 hour).
  4. User completes authorization → Ziniao callback pushes Token → the system automatically stores it in the database.
  5. Optional: call /tiktokShop/authorizedStores to confirm authorization succeeded.

Scenario 1b: Authorize TikTok video account (Creator)

User request: "I want to authorize my TikTok video account / help me bind my video account for selling"

Steps：

  1. Set appType to creator(dedicated for video account authorization); confirm region(for the US site use us, otherwise default global). Optionally ask for shopName as a display label.
  2. Call /tiktokShop/authorizeUrl, pass in {"appType": "creator", ...}, get authorizeUrl。
  3. Give authorizeUrl to the user, have them open it in a browser and complete video account authorization (the link expires in about 1 hour).
  4. User completes authorization → Ziniao callback pushes Token → the system automatically stores it in the database.
  5. When subsequently querying/refreshing the token for this video account,appType likewise pass creator。

Scenario 2: View Authorized Shops

User request: "List the TikTok shops I have authorized"

Steps：

  1. Call /tiktokShop/authorizedStores。
  2. to display the shop list (sellerName / openId / appType / region).

Scenario 3: Refresh Expired Token

User request: "My TikTok shop's token has expired, help me refresh it"

Steps：

  1. Call /tiktokShop/refreshToken, pass in openId（appType must be consistent with the authorization).
  2. Return the new accessToken / refreshToken and write it back to the database.
  3. If refreshToken has expired, guide the user to redo Scenario 1 authorization.

Scenario 4: Query Store Tokens

User request: "Get the access token for a TikTok shop"

Steps：

  1. Call /tiktokShop/storeTokens, pass in openId and appType。
  2. Return token information (for downstream developer agent calls).

Scenario 5: Prepare Token for Any Shop Operation (Standard Preparation Workflow)

When the user makes a request involving TikTok Shop backend data (querying products, orders, finances, etc.),this skill handles the preceding "select shop → get token" flow, and the business is taken over by the developer agent.

Steps：

  1. List authorized shops: call /tiktokShop/authorizedStores。
  2. Have the user select a shop: when there are multiple shops, ask the user to choose explicitly (note the distinction between appType）。
  3. Get the shop's token: call /tiktokShop/storeTokens, pass in openId and appType。
  4. Hand accessToken to the developer agentto execute the specific business call.

Display Rules

  1. Only present data: Simply display the authorization result, shop list, and token information; do not provide business advice.
  2. Security awareness: Do not display the full accessToken / refreshTokenin plaintext; only display it in masked form, such as the first 10 characters.
  3. Clear guidance: When returning the authorization link, clearly inform the user to open it in a browser and complete the authorization, and that the link expires in about 1 hour.
  4. Expiration interpretation：accessTokenExpireIn / refreshTokenExpireIn is an absolute Unix timestamp, and it must be compared with the current time to determine whether it has expired.
  5. Error explanation: When authorization or refresh fails, explain the reason based on the error code and provide suggestions.

Important Limitations

  • appType consistency: When querying/refreshing the token, appType must be consistent with that used during authorization (erp / creator / affiliate）。
  • Token validity period：accessToken is relatively short; if expired, use refreshToken to renew; ifrefreshToken has expired, reauthorization is required.
  • Authorization link validity：authorizeUrl is valid for about 1 hour; if expired, it must be obtained again.
  • User isolation: Users can only view/manage shops they have authorized.
  • Callback whitelist: The system callback URL and calling IP must be whitelisted with the authorizing party (Ziniao).

User Expression & Scenario Quick Reference

Applicable — Authorization and token management scenarios:

User Says Scenario
"Authorize my TikTok Shop" / "Authorize my TikTok Shop" New shop authorization (appType=erp)
"Authorize my TikTok creator account" / "Bind creator account for commerce" / "Authorize my TikTok creator account" Creator account authorization (appType=creator)
"Show my authorized TikTok shops" / "Show my authorized TikTok shops" List authorized shops
"My TikTok token expired" / "My TikTok token expired" Refresh token
"Get TikTok store access token" / "Get TikTok store access token" Query shop token
"Connect my TikTok Shop account" / "Connect my TikTok Shop account" New shop authorization

Not applicable — Business beyond this skill:

  • Pull business data such as TikTok Shop products / orders / finance → Completed through the developer proxy (carrying the accessTokenobtained by this skill).
  • TikTok product selection / creator commerce data analysis → Handled by other skills such as EchoTik.

Boundary judgment：

  • This skill is only responsible for "authorization + shop management + token management + preparing accessToken for downstream use".
  • When the user wants to perform specific backend business, first execute the standard prerequisite process in Scenario 5, and then the developer proxy completes the business logic.

Quick Reference

Authorization & Token Management APIs

API Path Purpose Auth Required
Get Authorization URL /tiktokShop/authorizeUrl Generate authorization link ✅ Yes
List Authorized Stores /tiktokShop/authorizedStores Query the user's shop list ✅ Yes
Query Store Tokens /tiktokShop/storeTokens Query the stored token for a shop ✅ Yes
Refresh Token /tiktokShop/refreshToken Refresh access token ✅ Yes

For detailed request parameters, response structures, and error codes, see references/api.md。

Feedback：

When any of the following situations occurs, automatically report feedback through the Feedback API:

  1. The functionality described by this skill does not match its actual behavior
  2. The skill's result does not match the user's intent
  3. The user expresses dissatisfaction with or appreciation for this skill
  4. Any point you think can be improved

According to references/api.md Call the Feedback API according to the specification in , without interrupting the user's main flow.

Handling Large Responses

To avoid overflowing the agent context, persist the response to disk and extract only the fields you need:

python scripts/response_io.py run --script scripts/authorize_url.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # or --path "<JMESPath>"

Pick --out-dir outside any git working tree (e.g. /tmp/... on Unix, %TEMP%/... on Windows). Persisted responses may contain PII, pricing, or auth-sensitive data — do not commit them. Files are not auto-deleted; clean up when the task is done.

This skill exposes multiple entry scripts: authorize_url.py, authorized_stores.py, store_tokens.py, refresh_token.py. Pass --script scripts/<name>.py to choose the one you need.

run writes the full response to a file and emits only a schema preview + file path. read projects specific fields, with --limit/--offset for slicing and --format json|jsonl|csv|table for output.

When to prefer this pattern — apply your judgment based on the response characteristics, e.g.:

  • High field count per record, or fields you don't need
  • Batch/paginated results (multiple items per call)
  • Long-text fields (descriptions, reviews, HTML, time series)
  • Output reused across later steps rather than consumed immediately

For small, single-use responses, calling the main script directly is fine.

⚠️ The preview is a truncated schema + sample, not the full data. Any field-level decision must read from the persisted file via read.

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