mirror of
https://github.com/truewhile/MeBox.git
synced 2026-10-14 00:56:37 +08:00
truewhile
104 lines
4.0 KiB
Markdown
104 lines
4.0 KiB
Markdown
## 获取设备码和二维码内容
|
|
|
|
### 基本信息
|
|
|
|
| 属性 | 内容 |
|
|
|:-----------|:---------------------------------|
|
|
| 接口名称 | 获取设备码和二维码内容 |
|
|
| 接口版本 | v1.0 |
|
|
| 接口路径 | /authDeviceCode |
|
|
| 请求方法 | POST |
|
|
| 接口状态 | 生产环境 |
|
|
|
|
### 接口说明
|
|
|
|
该接口用于 OAuth 2.0 + PKCE 手机扫码授权流程的第一步，获取设备码和二维码内容。此模式适用于无后端服务的第三方客户端，无需提供 AppSecret。
|
|
|
|
第三方客户端需要根据响应中的 `data.qrcode` 生成二维码，供 115 客户端扫码授权。
|
|
|
|
### 接口地址
|
|
|
|
```
|
|
https://passportapi.115.com/open/authDeviceCode
|
|
```
|
|
|
|
### 请求方式
|
|
|
|
```
|
|
POST
|
|
Content-Type: application/x-www-form-urlencoded
|
|
```
|
|
|
|
### 认证方式
|
|
|
|
```
|
|
OAuth 2.0 + PKCE
|
|
```
|
|
|
|
### 请求参数
|
|
|
|
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
|
|:---------------------|:-------|:---|:----|:--------------------------------|:-----------------------------------------------------------|
|
|
| client_id | string | 是 | - | AppID | `YOUR_APP_ID` |
|
|
| code_challenge | string | 是 | - | PKCE 挑战码 | `THHodGWg-FZfv8XYz7QArNGIK_aVomSHPldlSOTUtkw` |
|
|
| code_challenge_method | string | 是 | - | `code_challenge` 的哈希算法，见下方枚举表格 | `sha256` |
|
|
|
|
#### 请求参数中的 code_challenge_method 字段枚举
|
|
|
|
| 值 | 说明 | 备注 |
|
|
|:-------|:---------------------------|:---|
|
|
| md5 | 使用 MD5 计算挑战码 | - |
|
|
| sha1 | 使用 SHA-1 计算挑战码 | - |
|
|
| sha256 | 使用 SHA-256 计算挑战码，推荐使用 | - |
|
|
|
|
### 请求示例
|
|
|
|
```shell
|
|
curl 'https://passportapi.115.com/open/authDeviceCode' \
|
|
-H 'Content-Type: application/x-www-form-urlencoded' \
|
|
--data-urlencode 'client_id=YOUR_APP_ID' \
|
|
--data-urlencode 'code_challenge=THHodGWg-FZfv8XYz7QArNGIK_aVomSHPldlSOTUtkw' \
|
|
--data-urlencode 'code_challenge_method=sha256'
|
|
```
|
|
|
|
### 响应字段说明
|
|
|
|
| 字段 | 类型 | 描述 |
|
|
|:-----------|:-----|:------------------------------------------|
|
|
| state | int | 状态码 |
|
|
| code | int | 错误码 |
|
|
| message | string | 响应信息 |
|
|
| data | object | 响应数据 |
|
|
| data.uid | string | 设备码，轮询二维码状态时使用 |
|
|
| data.time | int | 校验时间戳，轮询二维码状态时使用 |
|
|
| data.qrcode | string | 二维码内容，第三方客户端需要据此生成设备二维码 |
|
|
| data.sign | string | 校验签名，轮询二维码状态时使用 |
|
|
|
|
### 响应示例
|
|
|
|
```json
|
|
{
|
|
"state": 1,
|
|
"code": 0,
|
|
"message": "",
|
|
"data": {
|
|
"uid": "DEVICE_CODE_PLACEHOLDER",
|
|
"time": 0,
|
|
"qrcode": "QRCODE_CONTENT_PLACEHOLDER",
|
|
"sign": "SIGN_PLACEHOLDER"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 注意事项
|
|
|
|
- `code_verifier` 为长度 43 至 128 位的随机字符串。
|
|
- `code_challenge` 的计算方式为 `url_safe(base64_encode(hash(code_verifier)))`。哈希结果按二进制数据参与 Base64 编码，算法需要与 `code_challenge_method` 一致。
|
|
- AppID 等应用凭证请使用实际应用配置，不要在公开仓库或日志中记录敏感凭证。
|
|
|
|
### 修改历史
|
|
|
|
| 修改时间 | 修改说明 |
|
|
|:-----------------------------|:-----|
|
|
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|