Docs

Explicit authorization

Explicit authorization is a targeted process utilizing the TTMinis.authorize interface that prompts a user with a pop-up dialog to grant specific permissions (defined by a scope), enabling your app to access additional details beyond a basic silent login.

You should only trigger this flow when a specific business scenario strictly requires extra information, such as accessing a user's profile data or binding a phone number.

Best practices

Consult the best practices for implementing explicit authorization:

Avoid immediate pop-ups: Do not launch an authorization dialog as soon as your Mini starts, as this significantly increases user churn and friction.
Prioritize silent login: Establish basic user identity first using silent login (TTMinis.login) to seamlessly retrieve the open_id.
Request contextually: Only ask for explicit permissions (TTMinis.authorize) when a specific business scenario strictly requires extra information, such as accessing a profile or binding a phone number.
Use user-initiated triggers: Initiate the authorization flow via a direct user action, like clicking a button, so the request feels natural and expected.
Secure token management: Always manage and store the resulting access_token and refresh_token securely on your backend server. Never expose them to the frontend.
Avoid local caching: Do not cache retrieved user data locally on the frontend to ensure the information you are using and displaying remains accurate and up-to-date.

Technical integration workflow

We don't recommend calling TTMinis.authorize to pop up an authorization box as soon as Minis starts, as it may easily lead to users refusing and affect conversion. It is suggested to first complete the basic login (get open_id), and then request users to authorize more permissions (such as obtaining user information, phone numbers, etc.) when necessary, and trigger authorization through buttons to avoid users' resentment.

If your platform needs to obtain additional user information such as username and avatar, use explicit authorization. This method necessitates user consent via an authorization screen.

Call the JavaScript API: Let the frontend call TTMinis.game.authorize , specifying the desired level of user data via the scope parameter.

Define scope: The scope user.info.basic tells the TikTok platform exactly what information you are requesting (in this case, basic user profile info like username and avatar). This triggers the user-facing pop-up.

Warning: Do not call this immediately when the user enters the game. Users may reject the request, and you will lose the chance to get their OpenID. Call this function only when the feature requiring the data (for example, a personalized leaderboard) is needed.

Success callback: If successful, the game receives an encrypted code, which is a temporary authorization code used for the next step.
Backend step (exchange code): The frontend must pass the obtained code to your server, so the server is able to exchange open_id and access_token by calling https://open.tiktokapis.com/v2/oauth/token/.
Backend step (get user data): After acquiring the access token, the server makes a second call to https://open.tiktokapis.com/v2/user/info/ to fetch the actual profile data (username, avatar) that the user explicitly authorized.

Example code:

TTMinis.authorize({
  // If you require other user permissions, please refer to https://developers.tiktok.com/doc/tiktok-api-scopes
  scope: "user.info.basic",
  success: (result) => {
    // The user has logged in and authorized the application
    // You can get the code, and send it to the backend to exchange for open_id, access_token
    let code = result.code;
  },
  fail: (error) => {
    // Other errors or unauthorized (user did not grant permission); code will be null
  },
  complete: () => {
    // This callback is triggered regardless of success or failure
  }
});

Learn more about TikTok's login and authorization JavaScript APIs.

Was this document helpful?