Skip to main content
Back to API docs

QR login workflow

TikTok QR Login API Workflow

QR login helps users connect TikTok accounts without a standard browser redirect. Your backend requests a QR session, your interface displays the QR image, and your system polls for status until the user confirms or the session expires. This flow is useful for custom products that want account linking inside their own application experience.

Request a QR code

Start by requesting a QR session from your server-side integration layer.

const API_BASE_URL = 'https://api.wahdx.com';
const API_KEY = process.env.WAHDX_API_KEY;

await fetch(API_BASE_URL + '/api/content/qr-login/request', {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    unique_id: 'my_session_12345'
  })
});

Poll QR status

After displaying the QR image to the user, poll every 2-3 seconds and always stop polling when the response is not OK, the session expires, the account is confirmed, the code is already used, or 5 minutes have passed.

const API_BASE_URL = 'https://api.wahdx.com';
const API_KEY = process.env.WAHDX_API_KEY;
const qrToken = 'TOKEN_FROM_STEP_1';
const startedAt = Date.now();
const maxPollingMs = 5 * 60 * 1000;

const intervalId = setInterval(async () => {
  if (Date.now() - startedAt > maxPollingMs) {
    clearInterval(intervalId);
    return;
  }

  const response = await fetch(API_BASE_URL + '/api/content/qr-login/check', {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ token: qrToken })
  });

  const result = await response.json();
  const status = result?.data?.status;

  if (!response.ok || ['confirmed', 'expired', 'utilised'].includes(status)) {
    clearInterval(intervalId);
  }
}, 3000);

Statuses to handle

Your UI should explain what is happening and recover cleanly if the session cannot complete.

  • new: QR code has not been scanned yet.
  • scanned: user scanned the QR code and needs to confirm.
  • confirmed: account linking completed successfully.
  • expired: request a new QR session.
  • utilised: the auth code has already been used.
  • 429 or non-OK response: stop polling and ask the user to retry later.

FAQ

Common questions about this API topic.

What is QR login used for?

It lets users connect TikTok accounts by scanning a QR code and confirming authorization in the TikTok app.

Should polling happen from the frontend?

The API key should stay server-side, so polling should be routed through your backend or server-side integration layer.

What happens when a QR session expires?

Stop polling immediately, request a new QR code, and show a clear recovery path to the user.