认证与登录 | 泡泡 IM 开发文档

用户仍然登录你自己的产品。你的后端确认“当前是谁”，再向 Popo IM 换取这个用户的 IM Token；客户端 SDK 拿到 Token 后加载聊天数据。
本文中的宿主就是接入 SDK 的网站或 App，宿主后端就是你已有的业务后端。authProvider 是客户端提供给 SDK 的取凭证函数，SDK 在登录和续期时调用它。
假设陈悦已经登录你的产品，业务账号 ID 为 chenyue：
/api/im-auth 是本文约定的示例地址，需要你在自己的后端实现；/app/sdk/token 是 Popo IM 已有的接口。客户端请求前者，你的后端请求后者。
配套应用已有 POST /app/auth/token，用已登录的 PHPSID 宿主会话获取 IM 凭证。继续使用这套账号系统时，参考随附宿主换取 Token；下面的自建取票接口用于接入你自己的账号系统。
sdkSecret（也称 SDK Secret）是你的后端访问 Popo IM 的密钥，不是某个用户的 Token。
完成安装向导后，在 Popo IM 服务器的项目根目录找到：
打开文件，读取 sdk_secrets 数组中的一个值。配置位置如下，仅展示相关字段，不要用这段示意覆盖整个文件：
安装器使用 bin2hex(random_bytes(32)) 生成 64 位十六进制字符串。当前版本通过此文件管理 SDKSecret，管理后台没有查看或修改入口。Docker 安装需在持久化的服务端源码目录中读取此文件。
把该值配置到你的业务后端。本文后端示例从以下环境变量读取：
这些变量名是示例的约定；仅在业务后端设置变量，不会自动修改 Popo IM 配置。密钥不能放入网页、App、前端构建变量、URL 或日志。
可以。sdk_secrets 支持同时保留多个密钥，适合分步更换：
密钥至少需要 32 字节，建议沿用安装器的生成方式。只修改 sdk_secrets，保留文件中的 token、group_invite 等其他配置。删除旧 SDKSecret 后，它不能继续取 Token；已经签发的用户 Token 仍按原到期时间生效。
先看请求结构，再按后端认证示例实现 PHP、Java、Go、JavaScript 或 C# 版本。
以下请求在你的后端执行。user_id 和资料来自后端已验证的当前账号，不能直接采用客户端传入的用户 ID。
user_id 是你业务账号的稳定、唯一 ID，大小写敏感。数据库的数字 ID 可转成字符串，例如 "1001"。不要使用昵称、手机号或每次登录变化的会话 ID；改变这个值，IM 会将其视为另一个用户。
资料不能含控制字符，ID 和昵称不能有首尾空白。每次取 Token 都会同步资料，应提交当前完整资料，避免下次续期覆盖已经更新的昵称或头像。signature 在这里指个性签名文案，与认证算法无关。
首次调用会自动创建 IM 用户，不需要再让用户注册一次 IM 账号。若希望在对方尚未登录 IM 时就能搜索或打开其资料，由后端先调用预置或同步用户。
成功响应如下，为便于阅读省略推送字段 push：
ID、Token 和时间仅作结构示意，使用实际响应值。user.id 是 IM 内部 ID；交给 SDK 的身份使用 user.user_id。expire_at 是 Unix 秒时间戳。
你的 /api/im-auth 在校验上游 HTTP 状态、code === 0 和必要字段后，以同样的 code / msg / data 结构返回给当前用户，并设置 Cache-Control: no-store。失败时返回可识别的错误；不要返回空 Token 或其他账号的结果。
需要原生推送配置时，取票请求还可携带 platform、manufacturer、package_name，三项一起传入；Web 无需提供。完整参数和 push 见获取 IM Token。先完成基础登录，再接推送。
authProvider 每次被调用时，都通过你产品已有的登录机制请求 /api/im-auth。它不接收要签发 Token 的用户 ID，也不保存 SDKSecret。
JavaScript 返回对象如下；完整请求代码见 Web 接入或 uni-app 接入：
初始化 SDK 一次，配置 Provider；在你产品的用户登录成功后再调用 login()。login() 在认证和首次同步完成后才成功返回。可选的 restoreCachedSession 只提前展示当前账号缓存，首次接入可先省略。
接入方无需计算请求签名，也无需自己生成 JWT。 后端携带 SDKSecret 换取 Token，SDK 使用返回的 Token。当前取票接口没有 timestamp / nonce / sign 参数；各语言实现见后端认证示例。
JWT 由三段组成：header.payload.signature。Popo IM 用 HMAC-SHA256（HS256） 计算最后一段：
Base64URL 使用 -、_ 替换普通 Base64 的 +、/，并去除末尾 =。HMAC 结果使用原始字节，再做 Base64URL 编码。
tokenKey 来自 Popo IM 自己的 token.keys[token.active_kid] 配置，不是 SDKSecret。JWT 头部含 alg: "HS256"、typ: "JWT"、kid；载荷含版本 ver、签发者 iss、内部用户 ID uid、宿主用户 ID user_id、签发时间 iat 和到期时间 exp。
服务端依据 kid 选密钥，重新计算签名并比较，同时校验版本、签发者、身份和时间。SDK 也会核对返回用户 ID、expireAt 与 JWT 一致，用于防串号和格式检查；最终验签仍在服务端。JWT 内容只是编码，没有加密，不能放入密码等私密资料。
算法说明用于理解和排错。token.keys 留在 Popo IM 服务器，无需复制给业务后端；日常更换 SDKSecret 也无需修改它。
SDK 负责 Token 续期，需要时会再次调用同一个 Provider。Provider 应始终能为当前宿主登录用户获取有效凭证，不能只返回首次登录时保存的固定 Token。
自动续期必须保持原账号。如果 Provider 在续期时返回另一用户，SDK 会停止旧会话并报告身份变化。不要在切换标签时反复初始化或退出 SDK。
宿主保存资料后，应更新后端取票使用的资料来源；若有取票缓存，同时让旧资料缓存失效。Web 用 refreshCurrentUser(user) 更新本地展示，后端另用用户预置接口同步到 IM；Android、iOS、HarmonyOS 和 uni-app 用 updateCurrentUser 在当前身份下提交资料变化。用户 ID 不能通过资料更新修改。
临时断网或服务不可用时，保留已有可读内容并允许重试。确认宿主登录失效时，清理 SDK 会话并回到宿主登录页。根据 HTTP 状态和业务错误码处理，不依赖错误文案；Token 和密钥不要写入日志或截图。
下一步：实现后端认证接口，然后返回 SDK 总览选择客户端平台。