Authorization overview (202407)
Requirements
Before the app can be authorized by online users, there are some pre-requisites for the app.
For custom apps:
- The app has enabled at least one API scope user: seller, creator, and/or partner.
- The app passes "enrollment review"
For public apps:
- The app has enabled at least one API scope user: seller, creator, and/or partner.
- The app passes "enrollment review"
- The app passes "USDS/OPIS review" (only for US target market)
- The app passes "Listing Review"
- The app passes "App review"
- The app passes "Beta Testing"(only for connector apps)
Enable API Scope
Before developing an app, the developer should enable or apply for the necessary API scope depending on the app's business type.
📌 Note: Enabling unnecessary scope(s) could result in a longer app review time and lower user authorization rate.
Obtain an authorization link
Generate an authorization link by clicking Copy authorization link in the Authorization section of your app:
📌 Note: If the app is in the development stage, the Copy authorization link button will be invisible. Please visit our seller authorization, creator authorization, or partner authorization guides for more information.
📌 Note: Depending on which market you are in, the authorization link will be slightly different.
US: https://services.tiktokshops.us/open/authorize?service_id=7369437808455026474
- ROW (rest of the world): https://services.tiktokshop.com/open/authorize?service_id=7431458374265161478
A state parameter should be added to your authorization link for extra security. Please see the OpenID Connect documentation for an example of how to create and confirm a state.
After the user visits the authorization link, they must accept or reject the authorization.
If the user accepts the authorization request, they will be redirected to the Redirect URL, which will additionally contain a temporary code as a parameter. This code will be used as the auth_code when obtaining an access token in the following step.
Redirect URL and auth_code example:
PLAINTEXTWord Wrap
{redirect_url}?code=FeBoANmHP3yqdoUI9fZOCw&state={state}
❗ Important: The auth_code expires in 30 minutes and can only be used once.
If the user rejects the authorization request, they will still be redirected to the Redirect URL, but instead the code will be null: code=null&error=auth_denied.
Get Access Token API
To request an access_token and refresh_token, make a GET request to the auth.tiktok-shops.com/api/v2/token/get endpoint, with the following parameters:
| Parameter | Type | Required? | Description | Sample |
|---|---|---|---|---|
| app_key | string | Yes | App key in Partner Center app page. | 123abc |
| app_secret | string | Yes | App secret in Partner Center app page. | 15abf8a4972afd1f275d5b19bfa9a17e0d142aa7 |
| auth_code | string | Yes | Authorization code obtained using the authorization link. | TTP_FeBoANmHP3yqdoUI9fZOCw |
| grant_type | string | Yes | Grant token type. Only authorized_code is accepted as a value. | authorized_code |
Your request should resemble the following:
PLAINTEXTWord Wrap
https://auth.tiktok-shops.com/api/v2/token/get?app_key=123abcd
&app_secret=15abf8a4972afd1f275d5b19bfa9a17e0d142aa7
&auth_code=TTP_FeBoANmHP3yqdoUI9fZOCw
&grant_type=authorized_code
If all the parameters entered in the GET request are valid, the response will contain the following parameters:
| Parameter | Type | Description | Sample |
|---|---|---|---|
| code | int | A machine-readable response code that represents the request result. 0 indicates success. For more information about failure codes, refer to Common error codes. | 0 |
| message | string | A human-readable message that describes the success or failure of the API request. | success |
| request_id | string | ID to track the API request. | 20220808094623010 |
| 24509910319695C45 | |||
| data | object | The response data payload. | |
| └ access_token | string | User access token needed to make calls to TikTok Shop Open API endpoints. Pass this value in the x-tts-access-token header of an API request to authorize the request. | TTP_RLM6CIADWF |
| 606TZGFO5XGA | |||
| └ access_token_expire_in | Unix timestamp | Expiration timestamp for access token, with default expiration time set to seven days. The unix timestamp represents the date and time the access token will expire. | 1630401330 |
| └ refresh_token | string | A token to refresh the access token. | TTP_C2XWDN63ON- |
| FOHJSMR0WSG | |||
| └ refresh_token_expire_in | Unix timestamp | Expiration timestamp for refresh token. The unix timestamp represents the date and time the refresh token will expire. | 1630401510 |
| └ open_id | string | An ID used to identify the user who has authorized the retrieval of their data in API calls. | ephr6QAAAADhos3OBM |
| ztFEwRCWQGzDmfXm_ | |||
| 7O2OTJyaYKA15pIaiEg | |||
| └ seller_name | string | The name of the seller you are authorizing for your app. | Test Name |
| └ seller_base_region | string | The region where the seller is based. | US |
| └ user_type | int | Type of user, with possible values: |
- 0: Seller
- 1: Creator
- 3: Partner | 1 | | └ granted_scopes | []string | The authorized API scopes for the app. This field will return the Scope Key value of the authorized API scopes.
| ["seller.affiliate_collaboration.read",
"seller.affiliate_collaboration.write"] |
PLAINTEXTWord Wrap
{
"code":0,
"message":"success",
"data":{
"access_token":"TTP_Fw8rBwAAAAAkW03FYd09DG-9INtpw361hWthei8S3fHX8iPJ5AUv99fLSCYD9-UucaqxTgNRzKZxi5-tfFMtdWqglEt5_iCk",
"access_token_expire_in":1660556783,
"refresh_token":"TTP_NTUxZTNhYTQ2ZDk2YmRmZWNmYWY2YWY2YzkxNGYwNjQ3YjkzYTllYjA0YmNlMw",
"refresh_token_expire_in":1691487031,
"open_id":"7010736057180325637",
"seller_name":"Jjj test shop",
"seller_base_region":"ID",
"user_type":0,
"granted_scopes": [
"seller.affiliate_collaboration.read",
"seller.affiliate_collaboration.write"
]
},
"request_id":"2022080809462301024509910319695C45"
}
Get Refresh Token API
To refresh your access_token, make a GET request to the auth.tiktok-shops.com/api/v2/token/refresh endpoint, with the following parameters:
| Parameter | Type | Required? | Description | Sample |
|---|---|---|---|---|
| app_key | string | Yes | App key in the TikTok Shop Partner Center app page. | 65t60877bfejb |
| app_secret | string | Yes | App secret in the Tiktok Shop Partner Center app page. | 15abf8a4972afd1f275d5b19bfa9a17e0d142aa7 |
| refresh_token | string | Yes | A refresh token obtained in the response parameters of the Get Access Token API. | TTP_C2XWDN63ON-FOHJSMR0WSG |
| grant_type | string | Yes | Grant token type. Only refresh_token is accepted. | refresh_token |
Your request should resemble the following:
PLAINTEXTWord Wrap
https://auth.tiktok-shops.com/api/v2/token/refresh?app_key=65t6a8e8bfejb
&app_secret=f4c770e4b45aa62e
&refresh_token=TTP_EB9rlwAAAADXbnMESTWAZSxIcC-XUA5AyeEOdmGBKY2FiKFYKqON6jco
&grant_type=refresh_token
If all the parameters entered in the GET request are valid, the response will contain the following parameters:
| Parameter | Type | Description | Sample |
|---|---|---|---|
| code | int | A machine-readable response code that represents the request result. | |
0 indicates success. For more information about failure codes, refer to Common error codes. | 0 | ||
| message | string | A human-readable message that describes the success or failure of the API request. | success |
| request_id | string | ID to track the API request. | 20220808094623010 |
| 24509910319695C45 | |||
| data | object | The response data payload. | |
| └ access_token | string | User access token needed to make calls to TikTok Shop Open API endpoints. Pass this value in the x-tts-access-token header of an API request to authorize the request. | TTP_RLM6CIADWF |
| 606TZGFO5XGA | |||
| └ access_token_expire_in | Unix timestamp | Expiration timestamp for access token, with default expiration time set to seven days. The unix timestamp represents the date and time the access token will expire. | 1630401330 |
| └ refresh_token | string | A token to refresh the access token. | TTP_C2XWDN63ON- |
| FOHJSMR0WSG | |||
| └ refresh_token_expire_in | Unix timestamp | Expiration timestamp for refresh token. The unix timestamp represents the date and time the refresh token will expire. | 1630401510 |
| └ open_id | string | An ID used to identify the user who has authorized the retrieval of their data in API calls. | jKlhBwAAAADxnvrRWZm |
| 0h5wx9isdVlL5tdIEOrGL_ | |||
| EZjSlhzJbuXt7_ | |||
| AZssO6oXnuIHC1NyR_ | |||
| ruluQnSaXetBDLjt_Y8d1JG | |||
| └ seller_name | string | The name of the seller you are authorizing for your app. | Test Seller |
| └ seller_base_region | string | The region where the seller is based. | US |
| └ user_type | int | Type of user, with possible values: |
- 0: Seller
- 1: Creator
- 3: Partner | 1 | | └ granted_scopes | []string | The authorized API scopes for the app. This field will return the Scope Key value of the authorized API scopes.
| ["seller.affiliate_collaboration.read",
"seller.affiliate_collaboration.write"] |
PLAINTEXTWord Wrap
{
"code":0,
"message":"success",
"data":{
"access_token":"TTP_Fw8rBwAAAAAkW03FYd09DG-9INtpw361hWthei8S3fHX8iPJ5AUv99fLSCYD9-UucaqxTgNRzKZxi5-tfFMtdWqglEt5_iCk",
"access_token_expire_in":1660556783,
"refresh_token":"TTP_NTUxZTNhYTQ2ZDk2YmRmZWNmYWY2YWY2YzkxNGYwNjQ3YjkzYTllYjA0YmNlMw",
"refresh_token_expire_in":1691487031,
"open_id":"7010736057180325637",
"seller_name":"Jjj test shop",
"seller_base_region":"ID",
"user_type":0
"granted_scopes": [
"seller.affiliate_collaboration.read",
"seller.affiliate_collaboration.write"
]
},
"request_id":"2022080809462301024509910319695C45"
}