Silent Login

Silent login is a mandatory capability for TikTok mini games that allows you to securely retrieve a user's unique OpenID and access token without requiring explicit user authorization. This eliminates the need for intrusive authorization popups on first launch, improving initial user experience and game launch rates while reducing user churn.

Use silent login when you only need a unique user identifier for core functionality like In-App Purchases (IAP), leaderboards, or save data synchronization. No user-facing authorization prompt is required.

If you need to access user information like display name or avatar, you will need to request additional scopes and may require explicit user authorization.

Prerequisites

Before integrating silent login, complete the following configurations in the Developer Portal:

• Complete privacy compliance requirements: You must provide valid Terms of Service and Privacy Policy URLs in your app settings.

• Verify credentials: Ensure you have the correct client key and client secret from the same app in the Developer Portal. Do not use credentials from other platforms as they will not work for TikTok mini games.

Integration steps

Step 1: Frontend gets temporary authorization code

Call the TTMinis.game.login API to get an authorization code (no user interaction required for silent login).

JavaScript example

TTMinis.game.login({
  success: (result) => {
    // Login successful, get authorization code
    const code = result.code;
    // Send code to your backend for token exchange
    sendCodeToBackend(code);
  },
  fail: (error) => {
    // Login failed (user canceled authorization or system error)
    console.error("Login failed:", error);
  },
  complete: () => {
    // Callback triggered regardless of success or failure
  }
});

Type definitions

// Success callback
type SuccessHandler = (result: {
  code: string;
}) => void;

// Fail callback
type FailHandler = (result: {
  error: {
    error_code: number;
    error_msg: string;
    error_extra: Record<string, unknown>;
  }
}) => void;

// Complete callback
type CompleteHandler = () => void;

For Unity C# SDK integration, refer to the TikTok Mini Game Unity SDK usage guide.

Step 2: Backend exchanges code for tokens

Your backend uses the temporary authorization code to exchange for an access_token, refresh_token, and the user's unique open_id.

API endpoint

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

Request headers

• Content-Type: application/x-www-form-urlencoded
• Cache-Control: no-cache

Request parameters

Request example

curl --location --request POST 'https://open.tiktokapis.com/v2/oauth/token/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cache-Control: no-cache' \
--data-urlencode 'client_key=CLIENT_KEY' \
--data-urlencode 'client_secret=CLIENT_SECRET' \
--data-urlencode 'code=CODE' \
--data-urlencode 'grant_type=authorization_code'

Success response

{
  "access_token": "act.example12345Example12345Example",
  "expires_in": 86400,
  "open_id": "afd97af1-b87b-48b9-ac98-410aghda5344",
  "refresh_expires_in": 31536000,
  "refresh_token": "rft.example12345Example12345Example",
  "scope": "user.info.basic,video.list",
  "token_type": "Bearer"
}

Error response

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter.",
  "log_id": "202206221854370101130062072500FFA2"
}

Important:

• The open_id is the unique identifier for the user in your game. Store this persistently in your database for user identification.
• Never exchange tokens directly on the frontend or expose your client_secret in client-side code, as this will cause security vulnerabilities.

Step 3: (Optional) Get user profile information

If you need to access the user's display name or avatar, use the access_token to call the user info API:

1. Call GET /v2/user/info/ with the access_token in the Authorization header.
2. The response will include display_name (user nickname) and avatar_url (user avatar URL).
3. Forward the avatar URL to the frontend for display.

Token management

Token validity periods

Refresh access token

The access_token expires after 24 hours, but you can refresh it silently without user interaction using the refresh_token.

API endpoint

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

Request parameters

Request example

curl --location --request POST 'https://open.tiktokapis.com/v2/oauth/token/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cache-Control: no-cache' \
--data-urlencode 'client_key=CLIENT_KEY' \
--data-urlencode 'client_secret=CLIENT_SECRET' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=REFRESH_TOKEN'

Best practices for token refresh

1. Proactive refresh: Refresh the access_token 10-30 minutes before it expires (based on the expires_in value) to avoid API call failures.
2. Token rotation: After a successful refresh, TikTok may return a new refresh_token. Always replace the old token with the new one in your database.
3. Fallback mechanism: If the refresh_token is invalid (returns invalid_grant error), notify the frontend to re-trigger the login flow to get a new authorization code.
4. Persistence: Store access_token, refresh_token, and their expiration times indexed by open_id in your database.

Troubleshooting

Credential and configuration issues

I get invalid_client error when exchanging tokens, what should I do?

• This is caused by mismatched Client Key and Client Secret:
• Ensure you are using credentials from the correct app in the TikTok Developer Portal (not from other platforms)
• Double-check that you copied both Key and Secret correctly, with no extra spaces or missing characters

Why is frontend login returning error code 102102?

• You haven't completed the privacy compliance requirements: Go to your app settings in the Developer Portal and fill in valid Terms of Service and Privacy Policy URLs. Temporary placeholder URLs are acceptable if you don't have official links ready.

Why is login returning a scope is invalid error?

• The scope you are requesting has not been approved for your app:
• Check the scopes passed in the login API call.
• Ensure the requested scopes have been applied for and approved in the Developer Portal app permissions list.

OAuth flow issues

Token exchange returns invalid_grant or code has been used error.

• The authorization code is invalid:
• Codes are one-time use only and expire after 5 minutes
• Ensure you use the code immediately after receiving it from the frontend
• Do not attempt to reuse the same code multiple times

API calls fail after 24 hours.

• Your access_token has expired:
• Implement the refresh token flow to get new access tokens automatically
• Do not force users to re-login unless the refresh token itself has expired

Technical implementation issues

Token exchange returns invalid_request error.

• Your request format is incorrect:
• Ensure the Content-Type header is set to application/x-www-form-urlencoded
• Check that the grant_type value is correct (authorization_code for code exchange, refresh_token for token refresh)
• Verify all required parameters are included and correctly encoded

Login success callback returns no code.

• The user canceled the authorization process:
• Handle this case gracefully in the fail callback
• Show a friendly user prompt, and re-trigger the login flow if necessary

Special use cases

Even if you only need the open_id and don't plan to use other APIs, you still need to complete the full token exchange process:

1. Send the authorization code from frontend to backend.
2. Call the token exchange API to get the open_id.
3. Store only the open_id in your database, you can ignore token expiration and refresh logic if you don't need to call other APIs.
4. Persist the open_id for future feature expansion (such as adding IAP or social features later).