跳到主要内容
版本：v4

扫码登录（设备码模式）

扫码登录基于 OAuth 2.0 设备码模式授权。接入端先向 TapTap 授权服务器获取 device_code 和 qrcode_url，再根据 qrcode_url 展示二维码。用户使用 TapTap 手机端扫码并确认授权后，接入端通过 device_code 轮询换取 Access Token 凭证，并将凭证交给接入方服务端完成 MAC Token 签算和用户信息获取。

授权流程​

获取设备码和二维码​

请求​

POST https://accounts.tapapis.cn/oauth2/v1/device/code
Content-Type: application/x-www-form-urlencoded

请求参数：

字段必选类型说明
client_id是string开发者中心申请的应用 client_id
response_type是string固定为 device_code
scope是string固定为 public_profile

响应​

字段类型说明
device_codestringDevice Code
expires_inintdevice_code 和 qrcode_url 的过期时间，单位为秒
intervalint设备尝试获取 Access Token 的时间间隔，单位为秒
qrcode_urlstring二维码展示 URL

成功响应示例（仅展示扫码登录使用的字段）：

{
  "data": {
    "device_code": "<DEVICE_CODE>",
    "expires_in": 300,
    "interval": 2,
    "qrcode_url": "<QRCODE_URL>"
  },
  "now": 1698292636,
  "success": true
}

接入端应根据 qrcode_url 生成二维码，并在 expires_in 过期前引导用户使用 TapTap 手机端扫码授权。

通过 Device Code 获取 Access Token​

请求​

POST https://accounts.tapapis.cn/oauth2/v1/token
Content-Type: application/x-www-form-urlencoded

请求参数：

字段必选类型说明
grant_type是string固定为 device_token
client_id是string开发者中心申请的应用 client_id
secret_type是string固定为 hmac-sha-1
code是string上一步获得的 Device Code

响应处理​

授权未完成时，接口会返回 HTTP 400，但仍需解析响应体中的 data.error：

  • success 为 true 时，data 中的对象即为 Access Token 凭证，其中包含 MAC Token 签算所需的 kid 和 mac_key。
  • data.error 为 authorization_pending 时，等待 interval 秒后继续轮询。
  • 其他错误根据 data.error 处理。

成功响应示例（仅展示 MAC Token 签算需要的字段）：

{
  "data": {
    "kid": "<KID>",
    "mac_key": "<MAC_KEY>"
  },
  "now": 1698292659,
  "success": true
}

错误响应示例：

{
  "data": {
    "code": -1,
    "msg": "请求错误",
    "error": "authorization_pending",
    "error_description": "oauth2.tapapis.com.AUTHORIZATION_PENDING: InvalidArgument: the end-user authorization is pending"
  },
  "now": 1698292640,
  "success": false
}

获取登录用户信息​

接入端获得 Access Token 凭证后，将凭证交给接入方服务端。接入方服务端使用其中的 kid 和 mac_key 按照 MAC Token 签算生成 Authorization 请求头，调用获取当前账户详细信息获取用户信息，可获得 openid、unionid、昵称 name 和头像地址 avatar。

错误码​

错误码详细描述
invalid_grant_codeDevice Code 无效，例如已过期或不存在
slow_downDevice Flow 中，设备通过 Device Code 换取 Access Token 的接口请求过于频繁
invalid_request请求缺少必需参数，包含不支持的参数或参数值，或者格式不正确
invalid_clientclient_id、client_secret 参数无效
server_error服务器出现异常情况，可稍等后重试，但需设置尝试上限，建议最多 3 次；如一直失败，则中断并告知用户
invalid_grant提供的 Access Grant 无效、过期或已撤销，例如 client_id 和 code_challenge 不匹配
authorization_pendingDevice Flow 中，用户未输入 user code，还没有对 Device Code 完成授权操作。按 interval 要求的频率继续轮询，直到 expires_in 过期
authorization_waitingDevice Flow 中，用户已经输入 user code，但还没有对 Device Code 完成授权操作。按 interval 要求的频率继续轮询，直到 expires_in 过期