¶ Query QR code status

Update time: 2025-07-23 07:34:21

This document is automatically generated based on https://github.com/authing/authing-docs-factory based on https://api-explorer.genauth.ai V3 API, and is consistent with API parameters and return results. If the document description is incorrect, please refer to V3 API.

According to the user scanning order, there are six states: not scanned, scanned and waiting for user confirmation, user consent/cancel authorization, QR code expired, and unknown error. The front end should give users different feedback through different states. You can learn the detailed process of scanning code login from the following article: https://docs.genauth.ai/v2/concepts/how-qrcode-works.html.

¶ Method name

AuthenticationClient.checkQrCodeStatus

¶ Request parameters

Name	Type	Is it required	Default value	Description	Sample value
qrcodeId	string	Yes	-	QR code unique ID

¶ Example Code

package test.authentication;

import cn.authing.sdk.java.client.AuthenticationClient;
import cn.authing.sdk.java.dto.CheckQRCodeStatusRespDto;
import cn.authing.sdk.java.dto.CheckQrcodeStatusDto;
import cn.authing.sdk.java.model.AuthenticationClientOptions;
import cn.authing.sdk.java.util.JsonUtils;

public class CheckQrCodeStatusTest {
    // Need to be replaced with your GenAuth App ID
    private static final String APP_ID = "AUTHING_APP_ID";
    // Need to be replaced with your GenAuth App Secret
    private static final String APP_SECRET = "AUTHING_APP_SECRET";
    // Need to be replaced with your GenAuth App Host
    private static final String APP_HOST = "AUTHING_APP_HOST";

    public static void main(String[] args) throws Throwable {
        AuthenticationClientOptions clientOptions = new AuthenticationClientOptions();
        clientOptions.setAppId(APP_ID);
        clientOptions.setAppSecret(APP_SECRET);
        clientOptions.setAppHost(APP_HOST);

        AuthenticationClient client = new AuthenticationClient(clientOptions);

        CheckQrcodeStatusDto reqDto = new CheckQrcodeStatusDto();
        reqDto.setQrcodeId("123");
        CheckQRCodeStatusRespDto response = client.checkQrCodeStatus(reqDto);
        System.out.println(JsonUtils.serialize(response));
    }
}

¶ Request response

Type: CheckQRCodeStatusRespDto

Name	Type	Description
statusCode	number	Business status code, which can be used to determine whether the operation is successful. 200 means success.
message	string	Description
apiCode	number	Segmented error code, which can be used to get the specific error type (successful request does not return). For a detailed list of error codes, please see: API Code List (opens new window)
requestId	string	Request ID. Returned when the request fails.
data	CheckQRCodeStatusDataDto	Response data

Sample result:

{
  "statusCode": 200,
  "message": "Operation successful",
  "requestId": "934108e5-9fbf-4d24-8da1-c330328abd6c",
  "data": {
    "status": "PENDING",
    "briefUserInfo": "Returned when the QR code status is scanned, authorized, or deauthorized. If "Web polling interface returns complete user information" is not enabled in the console application security - general security - login security - APP scan code login Web security (it is disabled by default), the interface will only return the user's avatar and display name. The front end can render the user's nickname and avatar based on this, giving the user a prompt that the code has been successfully scanned. ",
    "tokenSet": { "scope": "openid profile", "access_token": "eyJhbGciOiJSxxxxx", "id_token": "eyJhbGxxxx",     "refresh_token": "WPsGJbvpBjqXz6IJIr1UHKyrdVF", "token_type": "bearer", "expire_in": 7200
    }
  }
}

¶ Data structure

¶ CheckQRCodeStatusDataDto

Name	Type	Is it required?	Description	Sample value
status	string	Yes	QR code status. According to the order in which the user scans the code, there are six states: PENDING (not scanned), SCANNED (scanned and waiting for user confirmation), AUTHORIZED (user authorized), CANCELLED (authorization canceled), EXPIRED (QR code expired) and ERROR (unknown error).	PENDING
ticket	string	No	Returned when the QR code status is authorized. If "Web polling interface returns complete user information" is not enabled in Console Application Security - General Security - Login Security - APP Scan Code Login Web Security (disabled by default), this ticket will be returned to exchange for complete user information.
briefUserInfo	No	Nested type: QRCodeStatusBriefUserInfoDto.	`Returned when the QR code status is scanned, authorized, or deauthorized. If "Web polling interface returns complete user information" is not enabled in Console Application Security - General Security - Login Security - APP Scan Code Login Web Security (disabled by default), the interface will only return the user's avatar and display name. The front end can render the user's nickname and avatar based on this to prompt the user that the code has been successfully scanned.`
tokenSet	No	This data will be returned only when the QR code status is authorized and the "Web polling interface returns complete user information" switch (off by default) is turned on in the console Application Security - General Security - Login Security - APP Scan Code Login Web Security. It is recommended to use ticket to exchange for user information. Nested type: LoginTokenResponseDataDto.

¶ QRCodeStatusBriefUserInfoDto

Name	Type	Is it required?	Description	Sample value
displayName	string	Yes	User display nickname
photo	string	Yes	User avatar

¶ LoginTokenResponseDataDto

Name	Type	Is it required?	Description	Sample value
scope	string	no	Scope corresponding to access_token	`openid profile`
access_token	string	no	API call credentials, authorized to access resource API within a limited time	`eyJhbGciOiJSxxxxx`
id_token	string	no	User's identity credentials, which will contain user information after parsing	`eyJhbGxxxx`
refresh_token	string	no	refresh_token is used to obtain a new AccessToken	`WPsGJbvpBjqXz6IJIr1UHKyrdVF`

Previous article: Generate a QR code for login Next article: Use QR code ticket to exchange for TokenSet