Authing Docs

# API Refrence

Authing provides a REST-based scan code login interface, which developers can call directly.

POST
https://core.authing.cn/api/v2/qrcode/gene

Generate QR code for APP scan code login.

This interface will return QR code ID (random) and QR code link.

Headers
x-authing-userpool-id
REQUIRED
 string

User pool ID

Body Paramter
customeData
OPTIONAL
 string

Custom data fields will be written into the original data of the QR code.

scene
REQUIRED
 string

Scene value. For a constant value, fill in APP_AUTH.

200: OK

Field definition:

-random: The only sign of the QR code, which will be used for querying the status of the QR code and for the user confirmation authorization interface. -url: QR code image address. -expiresIn: The validity time of the QR code.

{
  "code": 200,
  "data": {
    "random": "SzZrszCJNCFfVBDUCKLDtAYNBR96SK",
    "expiresIn": 120,
    "url": "https://files.authing.co/user-contentsqrcode/5fae2648201cfd526f0ec354/SzZrszCJNCFfVBDUCKLDtAYNBR96SK.png"
  }
}

Example of generated QR code:

Use Online QR Code Decoding Tool (opens new window) to view the QR code data as follows:

{
  "scene": "APP_AUTH",
  "random": "SzZrszCJNCFfVBDUCKLDtAYNBR96SK",
  "userPoolId": "5fae2648201cfd526f0ec354",
  "createdAt": "2020-11-13T06:23:25.396Z",
  "expiresIn": 120,
  "customData": {}
}
GET
https://core.authing.cn/api/v2/qrcode/check

Query QR code scanning status

Query Parameters
random
REQUIRED
 string

QR code ID.

200: OK 
{
  "code": 200,
  "message": "Query the QR code status successfully!",
  "data": {
    "random": "SzZrszCJNCFfVBDUCKLDtAYNBR96SK",
    "userInfo": {},
    "status": 0,
    "ticket": null,
    "scannedUserId": null
  }
}

Request result field description:

  • status
    • 0: Code is not scanned.
    • 1: After scanning the code but the user has not clicked to agree to authorize or cancel authorization, the user's avatar and nickname will be returned at this time, but it does not contain other confidential information, which can be used for front-end avatar display.
    • 2: User agrees to authorization
    • 3: User cancels authorization
    • -1: Expired
  • userInfo:
    • By default, after the user scans the QR code, it will contain two fields: nickname and photo
    • Developers can also configure to return complete user information (including login credentials token)
  • ticket: used to exchange for complete user information. **This field will only appear after the user agrees to the authorization. **See below for details.
POST
https://core.authing.cn/api/v2/qrcode/userinfo

Use ticket in exchange for user information

Body Paramter
ticket
REQUIRED
 string

Query the ticket returned by the QR code status interface

200: OK 
{
  "code": 200,
  "message": "Successful in exchange for user information",
  "data": {
    "id": "5e05bbf2d51b3761d5c71070",
    "email": "983132@qq.com",
    "emailVerified": false,
    "oauth": "",
    "username": "983132@qq.com",
    "nickname": "",
    "company": "",
    "photo": "https://usercontents.authing.co/authing-avatar.png",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImVtYWlsIjoiOTgzMTMyQHFxLmNvbSIsImlxxxxxxxxx",
    "phone": "",
    "tokenExpiredAt": "2020-01-11T08:08:18.000Z",
    "loginsCount": 1,
    "lastIp": "::1",
    "signedUp": "2019-12-27T08:08:18.115Z",
    "blocked": false,
    "isDeleted": false
  }
}

Note: By default, this interface is only allowed to be called on the server side, that is, it needs to be initialized with the user pool key.

The default validity time of the ticket is 300 s.

Developers can access the Authing console (opens new window) Basic Configuration -> Basic Settings -> App scan code to log in to the Web Define the configuration to modify. **See the custom configuration item page for details. **

Custom configuration items
POST
https://core.authing.cn/api/v2/qrcode/scanned

Scan code marked on APP

Headers
x-authing-userpool-id
REQUIRED
 string

User pool ID

Authorization
REQUIRED
 string

User login credentials.

Body Paramter
random
REQUIRED
 string

QR code ID.

200: OK 
{
    code: 200,
    message: "Scan QR code successfully confirmed",
    data: {
        random: "", // return as is
        status: 0,
        description: "xxxx",
    }
}

The APP needs to meet two conditions:

  1. The user must be logged in
  2. The user's user pool ID matches the QR code user pool ID.
POST
https://core.authing.cn/api/v2/qrcode/confirm

The APP agrees to the authorization and the scanned interface needs to be called before calling this interface.

Headers
x-authing-userpool-id
REQUIRED
 string

User pool ID

Authorization
REQUIRED
 string

User login credentials.

Body Paramter
random
REQUIRED
 string

QR code ID

200: OK 
{
    code: 200,
    message: "Authorized login succeeded",
    data: {
        random: "", // return as is
        status: 1,
        description: "xxxx",
    }
}

The APP needs to meet two conditions:

  1. The user must be logged in
  2. The user's user pool ID matches the QR code user pool ID.
POST
https://core.authing.cn/api/v2/qrcode/cancel

To cancel authorization on the APP side, you need to call the scanned interface before calling this interface.

Headers
x-authing-userpool-id
REQUIRED
 string

User pool ID

Authorization
REQUIRED
 string

User login credentials.

Body Paramter
random
REQUIRED
 string

QR code ID

200: OK 
{
    code: 200,
    message: "Cancel authorization successfully",
    data: {
        random: "", // return as is
        status: -1,
        description: "xxxx",
    }
}

The APP needs to meet two conditions:

  1. The user must be logged in
  2. The user's user pool ID matches the QR code user pool ID.

← Custom configuration items →