# 完整接口列表

## 生成二维码

<mark style="color:blue;">`GET`</mark> `https://oauth.authing.co/qrcode/gene?userPoolId=xxx&scene=APP_AUTH&customVar1=xxx&customVar2=xxx`

返回二维码 ID 和二维码链接。

#### Query Parameters

| Name       | Type   | Description           |
| ---------- | ------ | --------------------- |
| customeVar | string | 自定义数据字段，可填任意多个。       |
| scene      | string | 场景值。为常量值，填 APP\_AUTH。 |
| userPoolId | string | 用户池 ID。               |

{% tabs %}
{% tab title="200 " %}

```
{
    "code": 200, // 200 表示正常
    "message": "生成二维码成功",
    "data": {
        "qrcodeId": "5e061366445c9985e5bf890a", // 二维码 ID
        "qrcodeUrl": "https://usercontents.authing.co/qrcode/5e061366445c9985e5bf890a.png" // 二维码链接
    }
}
```

{% endtab %}
{% endtabs %}

请求示例：[https://oauth.authing.co/qrcode/gene?userPoolId=59f86b4832eb28071bdd9214\&scene=APP\_AUTH\&customVar1=xxx\&customVar2=xxx](https://oauth.authing.co/qrcode/gene?userPoolId=59f86b4832eb28071bdd9214\&scence=APP_AUTH\&customVar1=xxx\&customVar2=xxx)

生成的二维码：

![](https://366491767-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdsKjoPVRBStTP-5zXe%2F-LxAQpSlzRkSs4UdaL4x%2F-LxARd7Blg5lxKDAJlH2%2Fimage.png?alt=media\&token=216aaa82-4bd2-4b88-aa4e-bf9601ca9582)

使用[在线二维码解码工具](https://cli.im/deqr) 查看二维码数据如下：其中 customVar1 和 customVar2 保存到了 userDefinedData 对象中。

```
{ 
   "scene":"APP_AUTH",
   "qrcodeId":"5e06c47da6b47a9433f8b3be",
   "userPoolId":"59f86b4832eb28071bdd9214",
   "createdAt":"2019-12-28T02:57:01.697Z",
   "expireAt":"2019-12-28T02:59:01.697Z",
   "userDefinedData":{ 
      "customVar1":"xxx",
      "customVar2":"xxx"
   }
}
```

## 查询二维码状态

<mark style="color:blue;">`GET`</mark> `https://oauth.authing.co/qrcode/check?qrcodeId=xxxx&scene=APP_AUTH`

#### Query Parameters

| Name     | Type   | Description           |
| -------- | ------ | --------------------- |
| scene    | string | 场景值。为常量值，填 APP\_AUTH。 |
| qrcodeId | string | 二维码 ID。               |

{% tabs %}
{% tab title="200 " %}

```
{
  "code": 200, // 业务状态码，200 表示正常
  "message": "查询二维码状态成功",
  "data": {
    "qrcodeId": "5e061489445c9985e5bf890d",
    "scanned": false,
    "expired": false,
    "success": false,
    "canceled": false,
    "status": 0,
    "userInfo": {},
    "ticket": "", // 该字段不一定会有
    "description": "二维码还没有被扫描"
  }
}
```

{% endtab %}
{% endtabs %}

请求结果字段说明：

* scanned: 二维码是否已经被扫描
* expired：二维码是否已经过期
* success：用户是否成功授权
* canceled：用户是否取消授权
* status
  * 0: 未知状态，即还未扫码，或者已经扫码但用户还没有点击同意授权或者取消授权。
  * 1: 用户同意授权
  * -1: 用户取消授权
* userInfo:
  * 默认情况下，在用户扫码之后，会包含昵称（nickname）和头像（photo）两个字段
  * 开发者也可以配置返回完整用户信息（包括登录凭证 token）
* ticket：用于换取完整用户资料。**此字段只有在用户同意授权之后才会出现。**&#x8BE6;情见下文。

## 使用 ticket 换取用户信息

<mark style="color:green;">`POST`</mark> `https://oauth.authing.co/oauth/scan-qrcode/exchangeUserInfoWithTicket`

#### Request Body

| Name   | Type   | Description         |
| ------ | ------ | ------------------- |
| ticket | string | 查询二维码状态接口返回的 ticket |

{% tabs %}
{% tab title="200 " %}

```
{ 
   "code":200,
   "message":"换取用户信息成功",
   "data":{ 
      "_id":"5e05bbf2d51b3761d5c71070",
      "email":"983132@qq.com",
      "emailVerified":false,
      "oauth":"",
      "registerMethod":"default:username-password",
      "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
   }
}
```

{% endtab %}
{% endtabs %}

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

ticket 默认有效时间为 300 s。

开发者可在 [Authing 控制台](https://authing.cn/dashboard) **基础配置** -> **基础设置** -> **App 扫码登录 Web 自定义配置** 处修改。**详情见自定义配置项页。**
{% endhint %}

{% content-ref url="customize" %}
[customize](https://authing.gitbook.io/authing/scan-qrcode/app-qrcode/customize)
{% endcontent-ref %}

## APP 端标记已扫码

<mark style="color:green;">`POST`</mark> `https://oauth.authing.co/oauth/scan-qrcode/scanned`

#### Headers

| Name          | Type   | Description |
| ------------- | ------ | ----------- |
| Authorization | string | 用户登录凭证。     |

#### Request Body

| Name     | Type   | Description |
| -------- | ------ | ----------- |
| qrcodeId | string | 二维码 ID。     |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
APP 端需要满足两个条件：

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

## APP 端同意授权

<mark style="color:green;">`POST`</mark> `https://oauth.authing.co/oauth/scan-qrcode/confirm`

#### Headers

| Name          | Type   | Description |
| ------------- | ------ | ----------- |
| Authorization | string | 用户登录凭证。     |

#### Request Body

| Name     | Type   | Description |
| -------- | ------ | ----------- |
| qrcodeId | string | 二维码 ID      |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
APP 端需要满足两个条件：

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

## APP 端取消授权

<mark style="color:green;">`POST`</mark> `https://oauth.authing.co/oauth/scan-qrcode/cancel`

#### Headers

| Name          | Type   | Description |
| ------------- | ------ | ----------- |
| Authorization | string | 用户登录凭证。     |

#### Request Body

| Name     | Type   | Description |
| -------- | ------ | ----------- |
| qrcodeId | string | 二维码 ID      |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
APP 端需要满足两个条件：

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