Explicit Authorization

Explicit authorization allows you to request access to a user's public profile information (display name and avatar) with their explicit consent. This is separate from silent login, which only retrieves the user's unique OpenID without any user interaction.

Understand the main features of TikTok's explicit authorization system:

1. No client-side user info APIs: TikTok does not provide frontend JS APIs like tt.getUserInfo or wx.getUserProfile that directly return user nicknames and avatars.
2. All user data via server-side APIs: All user profile information (nickname, avatar, etc.) must be retrieved by your backend through TikTok Open APIs.
3. Silent Login vs Explicit Authorization:
• TTMinis.game.login: Silently retrieves the user's OpenID without user awareness, used for core identification
• TTMinis.game.authorize: Explicitly shows an authorization popup to request user consent for specific permissions (like basic profile info)

Recommended flow

1. Phased authorization: Do not show the authorization popup immediately when the game launches. First use silent login to let users enter the game, and only request explicit authorization when needed (e.g., when displaying leaderboards or user profile pages).
2. Graceful degradation: If a user denies authorization, the game should still function normally with default avatars and placeholder names (for example, "TikTok Player") to avoid interrupting the user experience.

[Game Frontend (JS)]            [Your Backend]                [TikTok Platform]
       |                            |                             |
       |-- 1. TTMinis.game.login() ->|                             |
       | <--- AuthorizationCode ----|                             |
       |                            |                             |
       |-- 2. Send Code ------------>|                             |
       |                            |-- 3. Exchange for AccessToken ->|
       |                            |   POST /v2/oauth/token/     |
       |                            |                             |
       |                            |<-- AccessToken + OpenID ----|
       |                            |                             |
       |-- 4. TTMinis.game.authorize() ->|                        |
       |   (scope: user.info.basic) |                             |
       | <--- User taps "Allow" ----|                             |
       |                            |                             |
       |-- 5. Request user info ---->|                             |
       |                            |-- 6. Call User Info API ---->|
       |                            |   GET /v2/user/info/        |
       |                            |   (using AccessToken)       |
       |                            |                             |
       |                            |<-- Return Nickname & Avatar -|
       |                            |                             |
       | <--- Return user profile --|                             |

Integration steps

Step 1: Silent Login to get user identity (OpenID)

First, implement silent login to get the user's unique OpenID, which is required for all user-specific operations:

1. Frontend calls TTMinis.game.login to get an authorization code.
2. Frontend sends the code to your backend.
3. Backend exchanges the code for an access_token and open_id via the TikTok OAuth API.
4. Store the open_id, access_token, and refresh_token in your database indexed by the user's OpenID.

For complete implementation details, see the silent login guide for mini games.

Step 2: Request explicit user authorization

When you need to access the user's profile information (display name and avatar), call the explicit authorization API on the frontend.

JavaScript implementation

TTMinis.game.authorize({
  scope: "user.info.basic",
  success: () => {
    console.log("User has granted basic profile authorization");
    // Notify your backend to fetch user profile via Open API
    requestUserProfileFromBackend();
  },
  fail: (err) => {
    console.warn("User denied authorization", err);
    // Fall back to default profile display
    useDefaultUserProfile();
  }
});

• The only supported scope for mini games currently is user.info.basic for accessing basic profile information.
• If the user has previously granted authorization, calling this API will not show the popup again and will directly return success.
• Always handle the fail case gracefully to avoid blocking game progress.

Unity C# implementation

For Unity games, refer to the TikTok Unity SDK usage guide for platform-specific implementation details.

Step 3: Backend fetches user profile

This is the only valid way to retrieve user profile information. After the user completes explicit authorization, your backend uses the stored access_token to request user data.

API endpoint

GET https://open.tiktokapis.com/v2/user/info/

Request headers

Response fields

For complete API details, see the TikTok Server API reference.

Best practices

Use OpenID as database primary key

• Always use the user's open_id as the unique identifier for users in your database
• User avatars and nicknames may change over time, but open_id is permanent and immutable
• All virtual assets (coins, items, game progress) should be bound to the open_id, not to profile information

Call APIs only when needed

• TTMinis.game.login (Silent Login): Use only for retrieving OpenID, required for game entry, payments, and progress saving. It is completely silent and does not show any user interface.
• TTMinis.game.authorize (Explicit Authorization): Use only when you need to access the user's profile information.
• Important: The access token obtained from silent login alone cannot call the user info API. You must call tt.authorize once to get user consent before accessing profile data.

Combine backend persistence with frontend caching

• Backend: After obtaining user profile information, store the display name and avatar URL in your database associated with the user's open_id
• Frontend: Cache profile information locally using tt.setStorage to avoid blank interfaces during network loading when the user returns to the game
• Sync frequency: Refresh user profile information asynchronously every 3-7 days, do not call the user info API on every game launch

Configure server domain whitelist

• Add your backend API domain to the "Trust domains" list in the TikTok Developer Portal under Development Configuration.
• Without this configuration, all network requests (tt.request) will fail in both preview and production environments

Handle authorization denial gracefully

• If a user denies the authorization request, use a default avatar and "TikTok Player" as the display name placeholder
• Do not force users to exit the game or repeatedly show authorization popups if they deny permission, as this creates a poor user experience and may violate platform policies

Frequently Asked Questions

Why can't I find the tt.getUserInfo API?

• To protect user privacy, TikTok prohibits direct access to user profile information from the client side. You must follow the secure flow: backend exchanges for AccessToken → backend requests user profile via Open API.

Will the authorization popup appear every time?

• No. Once a user selects "Allow" or "Deny", the system caches their choice. To reset the authorization status, the user must revoke app permissions in their TikTok account settings.

Can users make payments without authorizing profile access?

• Yes. The payment flow only requires the open_id (obtained via silent login) and does not require users to grant profile access permission.