1. 使用指南
  2. /
  3. 对用户进行认证
  4. /
  5. 使用扫码登录认证
  6. /
  7. 使用自建 App 扫码登录网站
  8. /
  9. 完整接口列表

APP 扫码登录完整接口列表

更新时间: 2024-10-10 07:28:40
编辑

Authing 提供基于 REST 的扫码登录接口，开发者可以直接调用。

生成二维码

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

该接口会返回二维码 ID （random） 和二维码链接。

Headers
x-authing-userpool-id
REQUIRED
string

用户池 ID

Body Paramter
customeData
OPTIONAL
string

自定义数据字段，会写入二维码的原始数据中。

scene
REQUIRED
string

场景值。为常量值，填 APP_AUTH。

200: OK

字段释义：

  • random: 二维码唯一标志，查询二维码状态、用户确认授权接口会用到。
  • url: 二维码图片地址。
  • expiresIn: 二维码有效时间。
{
  "code": 200,
  "data": {
    "random": "SzZrszCJNCFfVBDUCKLDtAYNBR96SK",
    "expiresIn": 120,
    "url": "https://files.authing.co/user-contentsqrcode/5fae2648201cfd526f0ec354/SzZrszCJNCFfVBDUCKLDtAYNBR96SK.png"
  }
}

生成的二维码示例：

使用在线二维码解码工具 (opens new window) 查看二维码数据如下：

{
  "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 Parameters
random
REQUIRED
string

二维码 ID。

200: OK
{
  "code": 200,
  "message": "查询二维码状态成功！",
  "data": {
    "random": "SzZrszCJNCFfVBDUCKLDtAYNBR96SK",
    "userInfo": {},
    "status": 0,
    "ticket": null,
    "scannedUserId": null
  }
}

请求结果字段说明：

  • status
    • 0: 未扫码。
    • 1: 已经扫码但用户还没有点击同意授权或者取消授权，此时会返回用户的头像和昵称，但不包含其他机密信息，可用于前端头像展示。
    • 2: 用户同意授权
    • 3: 用户取消授权
    • -1: 过期
  • userInfo:
    • 默认情况下，在用户扫码之后，会包含昵称（nickname）和头像（photo）两个字段
    • 开发者也可以配置返回完整用户信息（包括登录凭证 token）
  • ticket：用于换取完整用户资料。**此字段只有在用户同意授权之后才会出现。**详情见下文。

使用 ticket 换取用户信息

POST
https://core.authing.cn/api/v2/qrcode/userinfo
Body Paramter
ticket
REQUIRED
string

查询二维码状态接口返回的 ticket

200: OK
{
  "code": 200,
  "message": "换取用户信息成功",
  "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
  }
}

注意：默认情况下，此接口只允许在服务器端调用，即需要使用用户池密钥初始化之后。

ticket 默认有效时间为 300 s。

开发者可在 Authing 控制台 (opens new window) 基础配置 -> 基础设置 -> App 扫码登录 Web 自定义配置 处修改。详情见自定义配置项页。

APP 端标记已扫码

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

APP 端标记已扫码，标记扫码之后 Web 端将可以获取到当前用户的昵称和头像。

Headers
x-authing-userpool-id
REQUIRED
string

用户池 ID

Authorization
REQUIRED
string

用户登录凭证。

Body Paramter
random
REQUIRED
string

二维码 ID。

200: OK
{
    code: 200,
    message: "二维码扫描确认成功",
    data: {
        random: "", // 原样返回
        status: 0,
        description: "xxxx",
    }
}

APP 端需要满足两个条件：

  1. 用户必须处于登录态
  2. 用户的用户池 ID 和二维码用户池 ID 匹配。

APP 端同意授权

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

APP 端同意授权，调用此接口前需要先调用 scanned 接口。

Headers
x-authing-userpool-id
REQUIRED
string

用户池 ID

Authorization
REQUIRED
string

用户登录凭证。

Body Paramter
random
REQUIRED
string

二维码 ID

200: OK
{
    code: 200,
    message: "授权登录成功",
    data: {
        random: "", // 原样返回
        status: 1,
        description: "xxxx",
    }
}

APP 端需要满足两个条件：

  1. 用户必须处于登录态
  2. 用户的用户池 ID 和二维码用户池 ID 匹配。

APP 端取消授权

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

APP 端取消授权，调用此接口前需要先调用 scanned 接口。

Headers
x-authing-userpool-id
REQUIRED
string

用户池 ID

Authorization
REQUIRED
string

用户登录凭证。

Body Paramter
random
REQUIRED
string

二维码 ID

200: OK
{
    code: 200,
    message: "取消授权成功",
    data: {
        random: "", // 原样返回
        status: -1,
        description: "xxxx",
    }
}

APP 端需要满足两个条件：

  1. 用户必须处于登录态
  2. 用户的用户池 ID 和二维码用户池 ID 匹配。