Manage Legacy User Access Tokens

Understanding the Basics

OAuth

TikTok Login Kit manages the token lifecycle, allowing you to integrate login and authentication flows directly in your application. A successful authorization flow grants developers refreshable access tokens. Those tokens enable developers to perform endpoint access with user permissions.

Authorization Scopes

Most endpoints provided by TikTok for Developers require direct consent from TikTok users before you can invoke them. The permissions are granted on a scope level. Users have the rights to only agree to a subset of scopes you requested from them.

Here are some example scopes:

• user.info.basic gives read-only access to a user's avatar and display name.
• video.list gives read-only access to a user's public TikTok videos.

You can learn more about Scopes on our Scopes Overview page.

Token Security

Tokens must be handled with extreme caution. We recommend storing and managing all tokens on the server side.

• Access token is a user authorization token that can be used to directly access user information in the Tiktok ecosystem.
• Refresh token is used to renew the access token.

Endpoints

1. Fetch Access Token Using Authorization Code

Once the authorization code callback is handled, you can use the code to retrieve the user's access token.

Endpoint

POST https://open-api.tiktok.com/oauth/access_token/

Request Query Parameters

Response.Data Struct

Make sure to store these values in your backend as they will be needed to persist access.

Code Example

app.get('/redirect', (req, res) => {
    const { code, state } = req.query;
    const { csrfState } = req.cookies;

    if (state !== csrfState) {
        res.status(422).send('Invalid state');
        return;
    }

    let url_access_token = 'https://open-api.tiktok.com/oauth/access_token/';
    url_access_token += '?client_key=' + CLIENT_KEY;
    url_access_token += '&client_secret=' + CLIENT_SECRET;
    url_access_token += '&code=' + code;
    url_access_token += '&grant_type=authorization_code';

    fetch(url_access_token, {method: 'post'})
        .then(res => res.json())
        .then(json => {
            res.send(json);
        });
})

If the request is not successful, the response will return the following error response body:

{
    "data": {
        "captcha": "",
        "desc_url": "",
        "description": "Parameter error",
        "error_code": 10002
    },
    "message": "error"
}

2. Refresh Access Token Using Refresh Token

Although the fetched access_token expires within 24 hours, it can be refreshed without user consent. The developer's backend server can schedule background jobs to keep tokens up to date.

Endpoint

POST https://open-api.tiktok.com/oauth/refresh_token/

Request Query Parameters

Response.Data Struct

Make sure to store these values in your backend as they will be needed to persist access.

Code Example

app.get('/refresh_token/', (req, res) => {
    const refresh_token = req.query.refresh_token;

    let url_refresh_token = 'https://open-api.tiktok.com/oauth/refresh_token/';
    url_refresh_token += '?client_key=' + CLIENT_KEY;
    url_refresh_token += '&grant_type=refresh_token';
    url_refresh_token += '&refresh_token=' + refresh_token;

    fetch(url_refresh_token, {method: 'post'})
        .then(res => res.json())
        .then(json => {
            res.send(json);
        });
})

If the request is not successful, the response will return the following error response body:

{
    "data": {
        "captcha": "",
        "desc_url": "",
        "description": "Parameter error",
        "error_code": 10002
    },
    "message": "error"
}

3. Revoke Access

When users want to disconnect the connection between your application and TikTok, you can revoke their access_tokens so the users will no longer see your application show up on the Manage app permissions page within TikTok.

Endpoint

POST https://open-api.tiktok.com/oauth/revoke/

Request Parameters

Response.Data Struct

Code Example

app.get('/revoke', (req, res) => {
    const { open_id, access_token } = req.query;

    let url_revoke = 'https://open-api.tiktok.com/oauth/revoke/';
    url_revoke += '?open_id=' + open_id;
    url_revoke += '&access_token=' + access_token;

    fetch(url_revoke, {method: 'post'})
        .then(res => res.json())
        .then(json => {
            res.send(json);
        });
})