Get widget token

Use Get Widget Token to generate a short-lived widget_token for TikTok Shop Widget SDK integration. The token flow is:

access_token and widget_token are different credentials. The access_token is used by the developer backend to call TikTok Shop Open APIs. The widget_token is a short-lived token passed to the Widget SDK.

Use the correct domain or interface for each part of the integration.

This API has no required business request parameters. Use only the common signed query parameters for normal calls.

curl --location --request GET 'https://open-api.tiktokglobalshop.com/authorization/202401/widget_token?app_key=<your_app_key>&timestamp=<unix_timestamp>&sign=<signature>' \
  --header 'Content-Type: application/json' \
  --header 'x-tts-access-token: <seller_access_token>'

{
  "code": 0,
  "data": {
    "widget_token": {
      "token": "<widget_token>",
      "expire_at": 1703100448
    }
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Your frontend should call your own backend endpoint to get the widget token. The backend should call TikTok Shop Open API and return only the short-lived widget token information.

async function getWidgetToken() {
  const response = await fetch('/api/widget-token', {
    method: 'GET',
    credentials: 'include'
  });
  const result = await response.json();

  if (result.code !== 0) {
    throw new Error(result.message || 'Failed to get widget token');
  }

  return result.data.widget_token;
}

When configuring @tiktokshop/widget-kit or @tiktokshop/widget-kit-react, pass this function to the SDK getToken field. The frontend SDK should receive a value with token and expire_at.

Widget SDK errors are handled separately from this Open API response. For example, /api/v1/seller/widget/get errors such as domain whitelist mismatch, expired widget token, invalid widget token, app key mismatch, or shop/region mismatch should be debugged in the Widget SDK integration layer.

You can test this API in the API Testing Tool or with a command-line client such as cURL. Before testing:

1. Confirm that the app is created and the App Key is correct.
2. Complete seller authorization and obtain a valid seller access_token.
3. Generate the sign value using the exact request path and query parameters.
4. Pass x-tts-access-token in the request header.
5. After receiving widget_token, verify that your frontend SDK getToken callback returns the object containing token and expire_at.