Login Kit with QR Code

Overview

This guide will explain how to integrate with the Login Kit to facilitate user authorization via QR code login. Once an authenticated user authorizes your app, you can access their basic TikTok profile data such as their display name and avatar. Additional data access may require approval for additional scopes. Learn more about scopes.

Prerequisites

Obtain a client key and client secret by logging into the TikTok for Developers website. Then go to the Manage apps page and select your app.

Security advisory: Verifying integrity using client_ticket

The client_ticket mentioned throughout this guide enables you to verify the data integrity of the response. While your app may still function even if you don't validate the client_ticket, doing so introduces security risks. Therefore, it is highly recommended that you always verify that the client_ticket matches the one generated by you, and reject any response where this validation fails as it may have been compromised by a malicious attacker.

Generating a client_ticket

Your client_ticket can be any series of characters, letters, or symbols, as long as it is URL safe and the URL-encoded version is under 512 characters. The generation method is at your discretion as there are no complexity requirements. You may reuse the same client_ticket, but some randomness is recommended for security. You should persist the ticket for the entirety of the QR code process as it will be needed when checking the validity of the QR status.

Integration

Your web app must implement the following functionality on the server side:

1. Generate a QR code.
1. Request a QR code URL (see the below sections for API guidance).
2. Generate a client_ticket.
3. Insert the client ticket into the QR code URL.
4. Render the URL.
5. Display it to the user.
2. Repeatedly check the QR code status and refresh or disable it accordingly (see the below sections for API guidance).
3. Parse the response for the provided authorization code once the QR code status is changed to confirmed.
4. Request an access token and refresh token from TikTok using the authorization code and client key.
5. Notify the user of authorization success or failure.
6. Use the access token to fetch authorized user data, and use the refresh token to extend the access token's expiration time.

For more information on access and refresh tokens, see Manage User Access Tokens.

Get QR Code

POST https://open.tiktokapis.com/v2/oauth/get_qrcode/

Description

Request a QR code from TikTok.

Header

Request

Example request

curl --location --request POST 'https://open.tiktokapis.com/v2/oauth/get_qrcode/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_key=aw7nk86b7czitwc9' \
--data-urlencode 'scope=user.info.basic,user.info.username' \
--data-urlencode 'state=key%3Dabc%26key2%3Ddef'

Response

A successful response will include the scan_qrcode_url and token fields. Once obtained, please perform the following steps:

7. Extract the scan_qrcode_url.
8. Generate a unique ticket using your preferred approach, such as an alphanumeric string such as 2ncv7awq. Persist this ticket alongside your service.
9. In the previously extracted scan_qrcode_url, replace the value of the client_ticket query parameter with your ticket. For example, scan_qrcode_url=...&client_ticket=tobefilled&... should be replaced by scan_qrcode_url=...&client_ticket=your_ticket&....
10. Use the modified scan_qrcode_url to generate a QR code.
11. Display the QR code to your user.

Example response

Success

{
    "scan_qrcode_url": "aweme://authorize?authType=100&client_key=abcd1234&client_ticket=tobefilled&...",
    "token": "VJ5JCKGJGRSWNMFWHQH4W5NKY943Q97D..."
}

Failure

{
    "error": "invalid_request",
    "error_description": "The request parameters are malformed.",
    "log_id": "202206221854370101130062072500FFA2"
}

Check QR code status

POST https://open.tiktokapis.com/v2/oauth/check_qrcode/

Description

Check the QR code status. Call with polling after the get_qrcode endpoint has been successfully called.

Header

Request

Example request

curl --location --request POST 'https://open.tiktokapis.com/v2/oauth/check_qrcode/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_key=aw7nk86b7czitwc9' \
--data-urlencode 'token=VJ5JCKGJGRSWNMFWHQH4W5NKY943Q97D' \
--data-urlencode 'client_secret=123fnaoif12n3ij'

Response

When the call succeeds, please perform the following steps:

12. Validate the client_ticket to make sure it matches what you provided in your generated ticket for the request. If they do not match, ignore the response as its integrity may be compromised.
13. Check that the status is confirmed and that the authorization code is appended in the redirect_uri.
14. If the status is not confirmed, continue polling if the status is not expired. If it is expired, then re-invoke the get_qrcode API.

Example response

Success

// A new generate QR code
{
    "client_ticket": "",
    "status": "new"
}
// A QR code scaned by the user
{
    "client_ticket": "your_ticket_string",
    "status": "scanned"
}
// A QR code confirmed by the user
{
    "client_ticket": "your_ticket_string",
    "redirect_uri": "https://example.com?code=example_code",
    "status": "confirmed"
}
// An expired QR code
{
    "client_ticket": "",
    "status": "expired"
}
// A QR Code after auth code returned
{
    "client_ticket": "your_ticket_string",
    "status": "utilised"
}

Failure

{
    "error": "invalid_request",
    "error_description": "The request parameters are malformed.",
    "log_id": "202206221854370101130062072500FFA2"
}