用户授权对接文档

1. 概述

本文档旨在帮助第三方合作方快速完成与我方的用户授权对接。

核心价值： 通过一次授权，第三方用户可与我方账号完成身份绑定。绑定后，我方推送的所有数据都将附带贵方的用户标识。

对接整体流程：

贵方引导用户打开我方授权页 → 用户登录/自动注册我方账号 → 用户确认授权 → 绑定完成 → 后续数据推送自动带上贵方用户标识

2. 对接前准备

在开始对接前，请联系我方获取以下信息：

信息项	说明
accessKey	贵方唯一标识，用于我方识别合作方身份
accessSecret	访问密钥，用于获取企业token来设置回调地址和签名
授权页地址	我方提供的授权页面URL: 测试环境：https://open-auth-test.lingcgm.com 正式环境：https://open-auth.lingsensebio.com

3. 第一步：设置贵方回调地址和接口签名

见设置回调地址

4. 第二步：引导用户打开授权页

贵方在需要绑定时，引导用户跳转至我方授权页面，并在URL中携带以下参数：

参数名	类型	必填	说明
accessKey	string	是	我方分配给贵方的唯一标识
thirdBizId	string	是	贵方系统中的用户唯一标识（即贵方的UID）

跳转示例：

https://auth.xxx.com?accessKey=AK_ABC123&thirdBizId=3rd_user_001

请注意：

thirdBizId 为贵方内部用户标识，请确保在贵方系统中可唯一识别一个用户

建议 thirdBizId 保持稳定，不要随会话或登录态变化

5. 第三步：用户登录/注册

用户打开授权页后，我方提供两种登录方式供用户选择：

方式一：手机号 + 密码登录

用户输入手机号及对应密码完成登录，适用于已注册并设置过密码的用户。

方式二：手机号 + 验证码登录

用户输入手机号后，点击获取验证码，系统将发送短信验证码至该手机号，用户输入正确的验证码即可完成登录。首次登录自动注册

整个登录/注册过程由我方页面承载，贵方无需额外处理。

6. 第四步：用户确认授权

登录成功后，页面自动跳转至授权确认页，向用户展示：

本次对接的合作方名称（贵方）

将共享的信息范围

授权用途说明

用户点击 “确认授权” 按钮，即完成授权。

若用户点击“拒绝”或关闭页面，授权流程终止。贵方可通过回调或主动查询获知状态。

7. 第五步：接收授权结果

用户确认授权后，我方会将授权结果回调至贵方设置的回调地址，确保先通过接口设置回调地址设置回调地址

回调参数：

字段	类型	描述
eventId	string	事件ID
eventType	string	固定为 `user_auth_event`
userId	string	用户ID
thirdBizId	string	第三方业务ID
eventTime	integer	事件时间，Unix 秒级时间戳
eventData.auth_status	boolean	授权状态：true-授权成功，false-取消授权
eventData.auth_message	string	授权结果描述

建议贵方：

收到回调后，记录授权成功状态

若未收到回调或回调失败，可调用我方提供的“查询用户授权状态”主动确认

8. 后续数据推送

授权绑定完成后，我方在向贵方推送任何数据时，都会在请求中附带 thirdBizId 字段。参考回调接口说明文档

贵方需要做的：

通过 thirdBizId 识别对应的用户

贵方内部维护好 thirdBizId 与自身用户体系的映射关系

9. 异常情况说明

可能遇到的情况	处理方式
授权页打开失败	检查网络，或联系我方确认服务状态
企业信息不存在	确认是否使用了我方分配的正确的 accessKey
验证码发送失败或错误	用户可重新获取验证码，注意60秒防刷限制
用户拒绝授权	授权流程结束，贵方可引导用户重新发起
回调未收到	调用“查询用户授权状态”主动确认绑定状态

10. 对接时序图

贵方用户            贵方系统              我方授权页           我方服务
   │                   │                    │                   │
   │  1.点击“授权绑定”  │                    │                   │
   │──────────────────>│                    │                   │
   │                   │  2.携带accessKey   │                   │
   │                   │  + thirdBizId      │                   │
   │                   │  跳转授权页         │                   │
   │                   │───────────────────>│                   │
   │                   │                    │                   │
   │                   │                    │  3.展示登录页      │
   │                   │                    │  (密码/验证码)     │
   │                   │                    │                   │
   │  4.选择方式登录/自动注册                 │                   │
   │───────────────────────────────────────>│                   │
   │                   │                    │                   │
   │                   │                    │  5.登录/注册成功   │
   │                   │                    │                   │
   │  6.展示授权确认页                       │                   │
   │───────────────────────────────────────>│                   │
   │                   │                    │                   │
   │  7.点击“确认授权”  │                    │                   │
   │───────────────────────────────────────>│                   │
   │                   │                    │                   │
   │                   │                    │  8.保存绑定关系    │
   │                   │                    │──────────────────>│
   │                   │                    │                   │
   │                   │  9.回调授权结果     │                   │
   │                   │<───────────────────│                   │
   │                   │                    │                   │
   │                   │                    │  10.后续数据推送   │
   │                   │                    │  (携带thirdBizId) │
   │                   │                    │──────────────────>│
   │                   │                    │                   │

11. 常见问题（FAQ）

Q1：thirdBizId 是什么？我需要怎么生成？

thirdBizId 是贵方系统内的用户唯一标识，直接使用贵方现有的 UID 即可。只需要确保在同一 accessKey 下，thirdBizId 与贵方用户是一一对应的关系。

Q2：手机号+验证码登录时，用户需要额外注册吗？

不需要。首次使用手机号+验证码登录时，系统会自动为手机号创建账号并完成登录，用户无感知，无需填写任何注册信息。

Q3：一个贵方用户可以授权多个我方账号吗？

不可以。在同一合作方下，一个 thirdBizId 只能绑定一个我方账号。如需更换，可先解绑再重新授权。

Q4：授权绑定后，如果用户在我方解绑了，会通知贵方吗？

用户解绑后，我方后续不会再推送任何。用户解绑时我方会推送解绑通知。

1. 概述#

2. 对接前准备#

3. 第一步：设置贵方回调地址和接口签名#

4. 第二步：引导用户打开授权页#

5. 第三步：用户登录/注册#

方式一：手机号 + 密码登录#

方式二：手机号 + 验证码登录#

6. 第四步：用户确认授权#

7. 第五步：接收授权结果#

8. 后续数据推送#

9. 异常情况说明#

10. 对接时序图#

11. 常见问题（FAQ）#