Design and Implementation of a QR‑Code Login Flow with API Interfaces

The article explains how to design and implement a QR‑code login workflow, targeting front‑end developers who need to understand both the product requirements and the technical steps required to build the feature.

Requirements: The QR code is valid for 2 minutes; after expiration the user must refresh it. After a successful scan, the mobile user confirms login, which then grants access to the web application.

Understanding: When generating a QR code, the backend creates an identifier and timestamps it for a 2‑minute lifespan. The front‑end displays the QR image, starts a timer, and continuously polls the backend to receive status updates such as QRCODE_SUCCESS , QRCODE_ERROR , or QRCODE_EXPIRE . These statuses drive the UI logic.

Flowchart: A visual flowchart (shown in the original article) outlines the sequence from QR‑code generation, scanning, confirmation, to final login.

API Design: Three REST endpoints cover the whole process:

1. QR‑code generation – POST /v1/accounts/qrcode/ . Request body includes platform and optional code . Response returns a png field containing a base64‑encoded QR image and metadata (id, expire, prefix, platform).

2. QR‑code scan – POST /v1/accounts/qrcode_fill . No body needed; user token is taken from the header. Response provides card_id , id , and step (SCAN, VERIFY, CANCEL).

3. Account login – POST /v1/passport/guest . The front‑end sends the QR‑code identifier in the code field and receives login status.

Example TypeScript interfaces from the article:

export interface Request {
    /**
     * 重新生成/取消时需要给
     */
    code?: string;
    platform: string;
}

export interface Response {
    /**
     * 二维码，前缀+base64串，格式：rk://scanforpclogin/{qrcode}
     * 二维码json解析结构
     * {
     * "id":"",
     * "expire":1685696389,
     * "prefix":"rk://scanforpclogin/",
     * "platform":"Rxx_PC"
     * }
     */
    png: string;
}

Front‑end implementation: The article shows how to request the QR code, convert the png to a data URL, and parse it with qrcode-parser :

V1CreateQRcode().then((res) => {
    qrcodeUrl.value = `data:image/png;base64,${res.data?.png}`;
    qrcodeParser(res.data?.png)
        .then((result) => {
            console.log(JSON.parse(result));
            QrCodeData.value = result ? JSON.parse(result) : null;
            recover();
        })
        .catch((err) => {
            console.log(err);
        });
});

After parsing, the front‑end starts a polling hook (implementation omitted) that repeatedly calls the login status endpoint until it receives a success, error, or expiration status.

Summary: The QR‑code login system relies on a 2‑minute expiration timer, backend‑generated identifiers, and clear status codes. The front‑end must display the QR image, poll the backend for scan/verification results, and handle refreshes when the code expires, enabling a smooth mobile‑to‑web authentication experience.