跳到主要内容

绑定第三方账户

POST 
/auth/v1/user/provider/bind

接口说明​

绑定第三方账户接口，用于将第三方身份源（如GitHub、微信、QQ等）绑定到当前登录用户账号，实现多种登录方式。

入参要求​

必填参数​

  • provider_token: 第三方身份源token（必填，通过 /auth/v1/provider/token 接口获取）
  • Authorization: 当前登录用户的access_token（必填，在请求头中传递，格式为 Bearer xxx）

可选参数​

  • with_user_center: 是否记录到用户中心化安全日志（可选，布尔值，默认false）
  • client_id: 客户端ID（可选，默认为环境ID）
  • x-device-id: 设备ID（可选，在请求头中传递）

前置条件​

  • 用户必须已登录（需要有效的access_token）
  • 用户必须在第三方平台完成授权
  • 必须调用 获取第三方授权信息 接口获取provider_token
  • 该第三方账号不能已被其他用户绑定

出参说明​

成功响应​

  • 返回空对象 {}，表示绑定成功

请求示例​

绑定GitHub账号请求示例​

{
  "provider_token": "your_provider_token",
  "with_user_center": true
}

响应示例​

绑定成功响应示例​

{}

Provider Token无效响应示例​

{
  "error": "invalid_grant",
  "error_code": 4001,
  "error_description": "Provider token无效或已过期"
}

未登录响应示例​

{
  "error": "unauthorized",
  "error_code": 4003,
  "error_description": "用户未登录或access_token无效"
}

字段说明​

请求参数​

字段名类型必填说明
provider_tokenstring是第三方身份源token，通过 /auth/v1/provider/token 接口获取
with_user_centerboolean否是否记录到用户中心化安全日志，默认false
client_idstring否客户端ID，默认为环境ID
x-device-idstring否设备ID，在请求头中传递
Authorizationstring是当前登录用户的access_token，格式为 Bearer xxx，在请求头中传递

响应参数​

字段名类型必填说明
-object是成功时返回空对象 {}

使用流程​

完整绑定流程​

1. 用户登录​

  • 用户必须先登录系统
  • 获取有效的access_token

2. 获取授权URL​

  • 调用 获取第三方登录回调地址 接口（可选，根据三方平台授权流程决定是否需要）
  • 获取第三方授权URL
  • 在新窗口或弹窗中打开授权页面

3. 用户授权​

  • 用户在第三方平台完成授权
  • 第三方平台回调并返回授权码

4. 获取Provider Token​

5. 绑定账号​

  • 调用本接口
  • 传入provider_token和access_token
  • 完成账号绑定

核心特性​

多账号绑定​

  • 支持绑定多个第三方身份源
  • 同一用户可绑定GitHub、微信、QQ等多个账号
  • 绑定后可使用任意已绑定的方式登录
  • 支持随时解绑

安全性​

  • 需要用户登录状态
  • provider_token有效期内使用
  • 防止重复绑定
  • 记录绑定日志

灵活性​

  • 支持多种身份源
  • 支持自定义身份源
  • 支持安全日志记录
  • 支持设备管理

使用场景​

账号绑定​

  • 用户在个人设置中绑定第三方账号
  • 方便使用多种方式登录
  • 提升账号安全性

社交账号关联​

  • 绑定GitHub账号
  • 绑定微信账号
  • 绑定QQ账号
  • 绑定微博账号

企业账号关联​

  • 绑定企业微信账号
  • 绑定钉钉账号
  • 绑定飞书账号

注意事项​

账号绑定限制​

  • 同一第三方账号只能绑定一个用户
  • 同一用户可以绑定多个不同的第三方账号
  • 不能绑定已被其他用户绑定的第三方账号
  • 绑定前会检查是否已存在绑定关系

Access Token​

  • 必须是有效的access_token
  • 必须在请求头中传递
  • 格式必须为 Bearer xxx
  • Token过期需要重新登录

解绑操作​

错误处理​

常见错误​

  • invalid_grant: Provider token无效或已过期
  • unauthorized: 用户未登录或access_token无效

错误处理策略​

  • provider_token无效：重新获取授权
  • 账号已被绑定：提示用户该账号已被使用
  • 未登录：跳转到登录页面
  • 身份源未配置：联系管理员
  • 达到绑定上限：解绑不常用的账号

相关接口​

Request​

Responses​

A successful response.

Response Headers