Skip to main content

Creator authorization guide

This guide is intended for​

  • apps that need to call Affiliate Creator APIs
  • integrations that need creator-side affiliate data or capabilities

What does creator authorization do?​

After creator authorization, the app can call Affiliate Creator APIs.

Core concept​

Creator authorization means:a creator grants your TikTok Shop app access to creator-side data and capabilities, so that your app can call the relevant Creator Open APIs.

At its core, the flow is still OAuth-based:

  1. Build an authorization link
  2. Let the user log in and approve authorization
  3. Receive a callback with code
  4. Exchange the code for tokens
  5. Use the token to call Creator APIs

Creator authorization is different from Seller authorization. A creator token and a seller token are different credentials and must not be reused interchangeably.

Prerequisites​

Before starting Creator authorization, make sure the following are ready:

App-side prerequisites​

  • the app is created
  • API access is enabled
  • a valid Redirect URL is configured
  • the required creator scopes are enabled or approved
  • if the creator capability is still beta / allowlist based, the app is approved for that rollout

Creator-side prerequisites​

the user is a real TikTok Shop creator, not just a regular TikTok account. The creator can enroll as a TikTok Shop creator by following the guides for the respective countries:

The creator's selection region must be one of the app's target markets:

If your app is in development, please contact your App Store Manager for a Creator testing account. Creator test accounts are only available to members of our beta phase today.

End-to-end authorization flow​

A practical Creator authorization flow can be understood in 7 steps:

  1. prepare the app
  2. enable creator scopes
  3. build the creator authorization link
  4. let the creator sign in and authorize
  5. receive code and state on the Redirect URL
  6. exchange the auth_code for access_token / refresh_token
  7. call Creator Open APIs and validate granted_scopes

Step 1: Prepare the app​

In Partner Center, make sure you have:

  • created the app / service
  • enabled API access
  • configured the Redirect URL
  • obtained app_key / app_secret
  • enabled the required creator scopes in Manage API

The Redirect URL is the callback destination after successful authorization. In production, it should be a real server-side endpoint that can validate the callback parameters, especially state.

Step 2: Enable creator scopes​

These are the creator scopes enabled or approved in Partner Center.

APP & Service -> Manage API，look for scope keys that begin with creator. For example：

The basic authorization link can be obtained from the Copy authorization link button.

For creator authorization links, you are required to manually add a state parameter for extra security. The state is an unguessable random string that can help protect cross-site request forgery attacks, and is not automatically included in the basic authorization link.

Please see the OpenID Connect documentation for an example of how to create and confirm a state. When encoding a state, remove leading and trailing white spaces.

Additionally, you may manually concatenate the entire authorization link by using your app_key and state.

The final authorization link should resemble:

PLAINWord Wrap

https://shop.tiktok.com/alliance/creator/auth?app_key={your_app_key}&state={your_state}

Parameters：

  • app_key: your application identifier
  • state: a security parameter that should be generated server-side

State best practices：

  • generate it on the server side
  • make it random and unpredictable
  • bind it to the current authorization session
  • validate it strictly on callback
  • treat it as single-use to reduce replay risk

Do not embed passwords, tokens, or other sensitive data directly into state.

Step 4: Let the creator sign in and authorize​

After opening the authorization link, the creator typically:

  1. signs in with the TikTok account
  2. enters the creator authorization page
  3. reviews the requested scopes
  4. if the authorization page supports partial authorization, the creator may toggle some scopes on or off (exact UI behavior to be verified)
  5. clicks Authorize

Engineering note: the creator may authorize only part of the requested scopes​

This means authorization success does not automatically mean all required business scopes were granted.

Step 5: Handle the callback and retrieve the auth code​

Official facts / interface constraints​

After the creator approves authorization, the platform redirects back to your Redirect URL with a temporary code. Here code is the parameter name returned in the callback URL; when you call Get Access Token, pass that same value as auth_code (evidence anchor: the callback example in this section + the parameter list in Step 6).

A typical callback looks like this:

PLAINWord Wrap

{redirect_url}?code={CODE_FROM_CALLBACK}&state={state}

Recommended implementation / engineering best practices​

Your callback handler should:

  • read code
  • read and validate state
  • detect callback errors if the user denied authorization
  • stop the flow if no valid code is returned

The auth_code should be treated as short-lived and usually single-use. Exchange it for tokens as soon as possible.

Step 6: Exchange the auth code for tokens​

Official facts / interface constraints​

Use the Get Access Token endpoint:

PLAINWord Wrap

GET https://auth.tiktok-shops.com/api/v2/token/get

Required parameters​

  • app_key
  • app_secret
  • auth_code (use the code returned by the callback URL)
  • grant_type=authorized_code

Key response fields​

  • access_token
  • refresh_token
  • open_id
  • user_type
  • granted_scopes

Recommended implementation / engineering best practices: validate immediately after token exchange​

Always verify:

  1. code == 0
  2. user_type == 1
  3. granted_scopes covers the minimum scopes required by your business

If these checks fail, do not move directly into business API calls.

Step 7: Refresh the token​

Official facts / interface constraints​

When the access token expires, refresh it with:

PLAINWord Wrap

GET https://auth.tiktok-shops.com/api/v2/token/refresh

Required parameters​

  • app_key
  • app_secret
  • refresh_token
  • grant_type=refresh_token

Recommended implementation / engineering best practices: after refreshing, re-check key fields​

  • user_type
  • open_id
  • granted_scopes

For safety, it is better not to assume the refreshed token behaves identically to the previous token. A safer engineering practice is to revalidate key fields whenever a new token is issued.

How to use granted_scopes properly​

granted_scopes is one of the most important fields in Creator authorization.

Use it at two levels:

Level 1: right after authorization​

Check whether the creator granted the minimum scopes your business requires.

Level 2: before feature execution​

Before calling an endpoint, confirm that the required scope is included in granted_scopes.

  • if authorization succeeded but scopes are incomplete, prompt the creator to reauthorize
  • if the API returns 105005, check both app scopes and token granted_scopes
  • if your product has multiple modules, maintain a scope-to-feature mapping

Partial authorization​

Creators can opt in or out what scope to authorize. A creator may not approve all scopes in one pass; callback success does not by itself mean all business-required scopes are available (evidence anchor: the granted_scopes field in the token response).

After calling [Get Access Token], please check the granted_scopes array in the response, and make sure the creator has authorized all necessary scopes.

The scope keys definition is on the Manage API page:

If the authorized scopes are not sufficient for your business, please ask the creator to "remove all access" and re-authorize again.

Reauthorization and deauthorization​

Official facts / interface constraints​

Creator authorization can be reasoned about through two lifecycle changes below. The exact product entry points for "remove all access" or disabling some scopes are still to be verified.

The creator removes all access​

Result:

  • the old token becomes invalid
  • future API calls fail with token invalid / deauthorized style errors

The creator disables some scopes​

Result:

  • APIs under those scopes will start failing with permission errors
  • a common error is 105005

Recommended implementation / engineering best practices​

Your app should therefore provide:

  • a clear way back to the authorization page
  • an understandable reauthorization flow
  • clear error messages for invalid tokens and missing scopes

Common errors and troubleshooting​

Error / scenarioMeaningSuggested action
105005Missing required scope at app level or token levelCheck app scopes, then check the token's granted_scopes, then ask the creator to reauthorize if needed
105002Access token expiredRefresh the token
105001 / token invalidToken invalid, revoked, or user removed all accessReauthorize if needed
101000Wrong token identity or wrong API-token pairingMake sure you are not using a seller token against a creator API
A practical rule of thumb:If a newly enabled scope still does not work, the first thing to inspect is usually the token's granted_scopes from the creator's latest authorization, not the app version number.

Best practices​

  1. generate and validate state on the server side
  2. persist granted_scopes
  3. store creator tokens separately from seller tokens
  4. exchange the auth code as soon as possible after callback
  5. request only the minimum necessary scopes
  6. provide a clear reauthorization entry in the product
  7. check scope capability before calling an API

FAQ​

Can a creator token and a seller token be reused interchangeably?​

No. They represent different user identities and should not be mixed.

Why did authorization succeed but the API still returns 105005?​

Usually because either:

  • the app does not have the required scope enabled, or
  • the token's granted_scopes does not contain the required scope

For safety, yes. A safer engineering practice is to revalidate key capability fields whenever a new token is issued.

What should I do if the creator granted only part of the requested scopes?​

Use granted_scopes to control feature availability, and reauthorize if a missing scope blocks critical business flows.

Missing parameter: The URL must include the "state" parameter for creators to authorize this app. Please contact the developer for assistance.​

For creator authorization links, you are required to manually add a state parameter for extra security. The state is an unguessable random string that can help protect cross-site request forgery attacks, and is not automatically included in the basic authorization link.

No data retrieved: The requested API list is empty. Please contact the app developer for more information.​

APP must open creator api scopes.

APP & Service -> Manage API, look for scope keys that begin with creator.