TikTok - Authentication & Database structure - OLD

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

Changed the requirements (to be stored into account but not visible into the UI); Added clarification “will not receive notification at this moment“; Added more clarification regarding refresh token; | | 03/06/2022 | 1.3 | OAuth Began - Added a system field in Account TikTok | | 09/06/2022 | 1.4 | Removed Warehouse ID field from Account TikTok. Added a dropdown field for choosing integration. | | 15/06/2022 | 1.5 | Added a diagram for the database tables. | | 04/07/2022 | 1.6 | N/A to Image ID , File, Warehouse fields; Certification Image field edited; | | 13/07/2022 | 1.7 | Product account TikTok table deleted; | | 16/07/2022 | 1.8 | Refresh token - updated requirement | | 22/08/2022 | 1.9 | Sandbox account details & credentials added | | 23/08/2022 | 2.0 | Endpoint changed for All others APIs | | 06/10/2022 | 2.1 | New requirement for access token (SD issue) |

Purpose of this document is to provide information on the TikTok authentication requirements & Database structure.

Sandbox account:

End points:

Auth: https://auth-sandbox.tiktok-shops.com

All others APIs: https://open-api-sandbox.tiktokglobalshop.com

Please note that we need to add the end points to integration in order to switch between sandbox and prod account

Credentials: TikTok sandbox shop: https://seller-sandbox.tiktok.com/uk/homepage

Username: sandbox_uklc_1ujluezusia@shop.tiktok.com Pass: 98dAQAiG8N3

Authentication

Docs: TikTok Shop Open Platform (tiktok-shops.com)

OAuth 1 Authentication.

First, we need to get an authorization code, using this link:

https://auth.tiktok-shops.com/oauth/authorize?app_key=123abc&state=123 which we have to generate based on the details we have in Integration Credentials and sent to the Account TikTok > Client email. From there once the link is followed we need to approve the authorization and in the url will receive the auth_code using callbacks.

Into this link, we need to replace app_key and state with our app_key & our state code. Example:

appKey = '123abc'//your key
state = ' 123abs'//your origin state
//expect url  below, trim the space
https://auth.tiktok-shops.com/oauth/authorize?app_key=key&state=123abs

After register, a redirect url would be required to obtain auth code. If requests are accepted, users will be redirected to the url with a temporary code. This code will be expired in 30 min and can only be used once.

{redirect_url}?code=FeBoANmHP3yqdoUI9fZOCw&state={the state you send}

In the generated link after the redirect we will get the field Auth_Code which is required for the integration(in order to get the Access token)

Once we get the authorization code, we need to “exchange“ it for an access token & refresh token:

1. Get Access Token

API Call: POST https://auth.tiktok-shops.com/api/token/getAccessToken

Docs: TikTok Shop Open Platform (tiktok-shops.com)

Addition 06/10/2022: We should refresh the access token on daily basis!

Request Parameters:

https://developers.tiktok-shops.com/console/app/view/5hlnbg/Basic_Info

Please note that referred account is sandbox account; | | app_secret | Your private app secret, please keep it as a secret. | string | Yes | N/A | We can get app secret from our account in TikTok: https://developers.tiktok-shops.com/console/app/view/5hlnbg/Basic_Info

Please note that referred account is sandbox account; | | auth_code | The code you obtain in the last step | string | Yes | N/A | | | grant_type | The way you grant token. Only "authorized_code" is accepted. | string | Yes | N/A | |

Example Response:

{
    "code": 0,
    "message": "success",
    "data": {
        "access_token": "LT5YWAs-Fes1J4nRbpPrQYxjWF2nNLoEnFC4hFzOdlkGOf4NUiSvcexpeu3ebLYT",
        "access_token_expire_in": 1652702709,
        "refresh_token": "NTExNGY0NzRhYTgwMjRkN2VkNmI0YjFlZTU4Yzg2YTA0YjM0YWI0ZWJhNzFjMA",
        "refresh_token_expire_in": 1683633909,
        "open_id": "7095672855853074178",
        "seller_name": "TestCase UK006"
    },
    "request_id": "202205091206590102452440220D2FE195"
}

Mapping:

Please note the access will be stored into the cache and the integration will need to check and refresh it when need. refresh token will be stored into the account but not visible in the UI) Once the refresh token is expired we also need to receive some sort of notification or error message (will not receive notifications at this moment). Once we have generated the access and the refresh token, we will need to regenerate the Access Token using the following:

2. Refresh Access Token

API Call: POST https://auth.tiktok-shops.com/api/token/refreshToken

TikTok Notes:

24 hours before AT expires: use this api to obtain your new access_token . Old token keep active until the expiration date. If you refresh too early, the current access_token will be returned.

After At expires & before RT expires: use this api can get a new access_token.

RT has expired: use this api can only get error code returned

After 2022 Mar 11, the expiration time of RT will not be extended after a successful refresh action. Instead, a new refresh token will be generated everytime you refresh.

As per document provided after refreshing the token, a new refresh token “refresh_token“ will be generated. When the access_token is about to expire, call the /api/token/refreshToken API with the new refresh token, that is, you can keep refreshing. If you keep refreshing before the refresh token expires, RT may never be out of date. But after 365, the shop must be re-authorized.

Request Parameters:

Example Response:

{
    "code": 0,
    "message": "success",
    "data": {
        "access_token": "RLM6CIADWF606TZGFO5XGA",
        "access_token_expire_in": 1630401330,
        "refresh_token": "C2XWDN63ON-FOHJSMR0WSG",
        "refresh_token_expire_in": 1630401510,
        "open_id": "7000636243100829446",
        "seller_name": "fanfan",
        "request_id":xxxx
    }
}

Mapping:

Sign generation:

https://developers.tiktok-shops.com/documents/document/234137

We are able to generate signature via postman, using this JS:

// Replace secret with your own
var secret = "8rt3d3a-9e8-7633-0045ec-62bad0gere"

function objKeySort(obj) {
    var newKey = Object.keys(obj).sort()
    var newObj = {}
    for (var i = 0; i < newKey.length; i++) {
        newObj[newKey[i]] = obj[newKey[i]]
    }
    return newObj
}

function getEnvVar(k) {
    var v = pm.variables.get(k)
    if (v != null) {
        return v
    }
    v = pm.environment.get(k)
    if (v != null) {
        return v
    }
    v = pm.globals.get(k)
    if (v != null) {
        return v
    }
    return null
}

var ts = Date.parse(new Date()) / 1000
pm.variables.set("timestamp", ts)

calSign = function(secret) {
    var ts = getEnvVar("timestamp")
    var queryParam = pm.request.url.query.members
    var param = {}
    for (var item in queryParam) {
        if (queryParam[item].key == "timestamp") {
            v = ts
        } else {
            var v = queryParam[item].value
            if (v == null || v == "{{" + queryParam[item].key + "}}") {
                v = getEnvVar(queryParam[item].key)
            }
        }
        param[queryParam[item].key] = v
    }

    delete param["sign"];
    delete param["access_token"]
    var sortedObj = objKeySort(param)
    var signstring = secret + pm.request.url.getPath()
    for (var key in sortedObj) {
        signstring = signstring + key + sortedObj[key]
    }
    signstring = signstring + secret
    console.log(signstring)
    sign = CryptoJS.HmacSHA256(signstring, secret).toString()
    return sign
}

var sign = calSign(secret)
pm.variables.set("sign", sign)

Database Structure

Here is a diagram showing the newly created tables for the integration and their relation to the existing ones.

Integration Credentials - here we store our application ids. Please note this table is not visible in the UI and the details are the same for all instances.

Also we need to create a new record for TikTok in Integration table.

Account TikTok - here we store the required details for the integration. Slave table of Account table used for the account setup: