功能说明​

账号密码、短信（含别名）、邮箱登录及二维码 check 共用本页规则。本文对照当前服务端实现编写，不代表目标环境已经部署或完成真实 IM 验收。示例均为虚构值或占位符。

请求参数​

设备字段直接放在登录请求 JSON 顶层，不嵌套在 device 中。二维码待登录端在 check 时提交，扫码确认端不代传。

先通过对应端 IM SDK 的 getDeviceId 能力获取设备标识，再调用业务登录；具体对象及同步/异步调用形式以所集成 SDK 版本为准。Web、桌面容器也必须使用实际 IM 连接侧的同一标识，不要另随机生成业务 ID 或每次登录更换 ID。当前 IM 撤销适配器拒绝含逗号的目标 ID，因此登录校验接受此类 ID 也不能保证删除完成。

兼容期与重新登录​

• 服务端按应用配置 device_auth_required_at（Unix 毫秒）；缺省/0 或尚未到正数截止时间时，只有 device_id、platform 两个键同时未提交才允许旧登录，展示字段仍需通过校验。
• 只传一个身份键、空字符串、显式 null、错误类型、非法枚举均不是兼容请求，返回 17601；展示字段类型错误可能先由 handler 返回 17003。
• 达到截止时间（含相等）后，两个键均未提交返回 17605。version 请求头不决定设备字段要求。
• 新登录返回用户设备会话，当前凭证格式为 ds1...，会话类型为 user_session。客户端将其视作不透明字符串，不自行构造、修改或推算有效期。同应用、同用户、同设备再次登录会替换会话，之前该设备的业务凭证失效。
• 展示字段可不传；同设备再次登录时，未传展示字段会覆盖为空字符串，last_active_time 重置为 null。
• 旧登录不登记受管理设备，可能不出现在设备列表；兼容期不能承诺严格设备身份防绕过，安装标识也不是不可伪造的硬件身份。
• 设备会话失效后需携带同一 SDK 设备身份重新登录；封禁/撤销未完成时按 17607 处理，不要反复更换设备 ID。

登录响应​

四类登录成功都使用以下结构：

{
  "code":0,
  "msg":"success",
  "data":{
    "user_id":"demo-user",
    "authorization":"<业务凭证>",
    "nickname":"示例用户",
    "avatar":"",
    "status":0,
    "im_token":"<IM连接凭证>"
  }
}

user_id、authorization、nickname、avatar 为 string；status 为 int，当前登录返回 0，不表示设备在线状态。im_token 为 string，空值时可省略。新旧登录响应字段一致。

authorization 用于业务 HTTP，原样放在 Authorization 请求头，不加 Bearer ；im_token 用于 IM SDK 连接，不能互换。Bearer 在本服务表示 API Key，不可用于设备管理或扫码确认；内部服务凭证也不可用于这些接口。凭证和二维码秘密不写入 URL、埋点或普通日志。

响应结构与错误码​

通常 HTTP 200 也可能业务失败，必须检查 code；同时处理网络失败及非 2xx。部分登录 handler 的 BindJSON 对畸形 JSON 可能先设置 HTTP 400。

成功（包括扫码确认的空数据）为 {"code":0,"msg":"success","data":null}。原有通用错误通常不含 data，例如 {"code":17005,"msg":""}。设备/新版 QR 错误由 deviceError 输出 HTTP 200，始终带 data，可为 null：

{"code":17601,"msg":"invalid device parameters","data":null}

不要依赖 msg 判断状态，也不要假设所有错误都有相同字段。

登录也先执行原有账号/验证码和 IM 注册逻辑，不保证设备参数错误优先返回；上游 IM 非零码可能原样透传，需保留未知错误兜底。

17607 的 data 与设备删除任务不同：

{"code":17607,"msg":"device banned or revocation pending","data":{"banned_until":1793751000000,"retry_after_seconds":600}}

banned_until 为 Unix 毫秒；retry_after_seconds 为向上取整且不小于 0 的秒数。撤销未完成即使超过截止时间也会拒绝登录，秒数为 0 不表示可以立即登录。

鉴权中间件先于 handler：缺少 Authorization 通常 17005；旧 token 在兼容期请求设备接口也通常被中间件以 17005 拒绝，不能一律写成 17605；API Key/服务凭证访问敏感路径通常 17604。

设备管理入口​

登录后通过 设备列表 查看在线/离线设备，通过 删除其他设备 撤销目标设备。列表消失、操作 ID、倒计时结束都不是 IM 删除完成证明。