身份与登录

取得当前用户在本应用内的身份，并建立自己的业务登录态。准备 AppSecret、已配置的业务登录域名，以及支持登录的宿主。正式版要求 active 应用；已选定的体验版支持 draft/active 应用，当前账号须具有本应用有效项目成员或体验成员资格，无需先正式发布或激活。首包上传前的本地调试还需要可信工具与宿主接入调试上下文。

四方职责

调用方	负责内容	持有材料
小程序 JS	调用 wx.login，把一次性 code 交给自有业务后端	一次性 code、业务登录态
宿主	确认当前用户和应用，向平台申请登录码	宿主 UUMS 身份，不向 JS 暴露
应用后端	按微信 code2Session 协议兑换 code，以 openid 建立业务登录态	AppSecret、session_key、业务登录态
平台	签发和消费登录码，维护应用内身份与会话有效性	应用作用域身份和运行治理状态

资料与身份的边界（40.16.0 候选）

业务身份使用本页的 wx.login → 自有业务后端 → jscode2session 链路。当前匿名资料规则下，wx.getUserInfo、wx.getUserProfile 不提供真实宿主 UID、昵称或头像；清单声明 host-user-info 也不代表用户同意复用资料。旧 community.host.getUserInfo 和旧原生资料消息将明确返回 miniapp_host_user_info_retired，业务应迁移到 code 登录和自行维护的资料，不能把空 UID、游客或 fallback 当作登录成功。

普通 wx.getUserInfo({withCredentials:false, success, fail, complete}) 采用回调且返回 void；匿名读取不要求先建立应用登录态。需要签名和密文时，先正常调用 wx.login，再调用 wx.getUserInfo({withCredentials:true, success, fail, complete})；可以把 code 与资料凭据一起通过普通 wx.request 交给业务后端，后端随后兑换 code，使用所得同一 session_key 验签和解密。也可先兑换再读取资料，不强制业务兑换顺序。密钥只由后端保管，不能交给宿主、JS 或日志。SDK 的 uni facade Promise 适配与普通 wx 返回值分开。

本候选仅接入 wx.getUserInfo。wx.getUserProfile 无应用会话时的精确凭据字段组合、完整 Unicode 长度边界尚未独立核验；用户未接受以“无会话仅返回匿名资料、不返回凭据”作为 Test 差异，因此该 API 的新增实现已撤出本候选，暂不开放，不新增强制登录步骤或伪造凭据替代。原型保留待核验。本候选仍需 SDK 与宿主配套升级，两端真实设备结果及实际开放时间以兼容矩阵、站点运行版本和发布记录为准；服务端检查通过不代表全部客户端能力已开放。

code 换取 session

使用宿主体验版调用 wx.login 与 wx.request。以下业务登录地址由应用自行实现，并加入请求域名；它不属于平台 API：

wx.login({
  success({ code }) {
    if (!code) return
    wx.request({
      url: 'https://api.example.com/login',
      method: 'POST',
      data: { code },
      success(response) {
        // 同时检查业务后端的 HTTP 状态和业务结果。
        // 只接收应用自己的登录态，不接收 AppSecret 或 session_key。
      },
      fail() {
        // 提示用户本次登录未完成，重新发起时获取新的 code。
      }
    })
  },
  fail() {
    // 按当前宿主返回的失败原因处理，不伪造 code。
  }
})

小程序通过 wx.login 取得 code 并提交给应用后端。code 有效期为 5 分钟且只能使用一次。应用后端调用与微信相同的路径、方法和参数；只需将 API Origin、App ID 和 AppSecret 配置为 MetaEco 分配值：

curl --get "$PLATFORM_ORIGIN/sns/jscode2session" \
  --data-urlencode "appid=$APP_ID" \
  --data-urlencode "secret=$APP_SECRET" \
  --data-urlencode "js_code=$LOGIN_CODE" \
  --data-urlencode "grant_type=authorization_code"

成功响应：

{
  "openid": "oid_0123456789abcdef0123456789abcdef0123456789abcdef",
  "session_key": "MDEyMzQ1Njc4OWFiY2RlZg=="
}

兼容接口处理的失败响应保持 HTTP 200，正文使用 errcode、errmsg；网络或网关错误仍可能没有该结构。40029 表示 code 无效或已过期，40163 表示 code 已消费，40125 表示 AppSecret 不可用，-1 表示系统暂不可用。先修正凭据、应用状态或依赖问题，再重新执行 wx.login；响应丢失或 code 已消费时也不要重试同一 code。

平台尚未提供跨应用 UnionID 机制，因此成功响应不含 unionid。openid 在同一 App ID 内稳定，不得用于跨应用关联。

本地开发登录

本地浏览器预览只用于检查页面，模拟 code 不能用于登录兑换。平台后端允许有开发权限的成员为 draft 或 active 应用创建本地调试上下文，无需先上传版本；可信工具与宿主携带调试凭证签发真实 code，应用后端仍按上节 /sns/jscode2session 流程兑换。有效调试 code 和具有当前体验资格的已上传体验版 code 都可在 draft 阶段兑换；正式版仍要求 active。调试会话过期、撤销、开发权限撤回或应用停用后，相关登录码和会话失效；体验资格撤销/到期或体验包取消后，旧体验 code/session 也不再准入。当前提供的构建工具未接入该宿主调试流程，需使用已接入该能力的工具与宿主验证本地调试链路；已上传体验包走既有体验通道。

session_key 与业务登录态

session_key 是标准 Base64 编码的 16 字节 AES 密钥，只能保存在应用后端，用于兼容微信开放数据签名和 AES-128-CBC 解密，也作为现有平台会话接口的 X-MiniApp-Session 凭据。禁止将它写入日志、URL、业务 JWT 或返回给小程序。

应用后端应基于 openid 创建自己的业务登录态。平台在 wx.login 时内部建立客户端会话，业务后端随后兑换 code 取得对应密钥；同一有效账号、应用及运行上下文可复用密钥。平台会话采用滑动有效期；账号或运行上下文切换、关闭/撤销、版本下架或应用停用可使旧会话失效，旧 code 不能兑换成新会话的密钥。这些操作不会自动删除应用后端已经签发的业务 token。

支持 wx.checkSession 的 SDK/宿主组合可在 wx.login 成功后直接检查客户端登录态，不要求业务后端先兑换。当前发布组合的开放情况见SDK 方法差异。业务后端需要校验已保存的平台会话时，按下节调用。

应用后端校验与退出

应用后端需要核对已保存的平台会话时，可使用会话校验。SESSION_KEY 是本次登录兑换得到的 session_key，ACCESS_TOKEN 是本应用当前接口 token，均仅保存在服务端：

curl --request POST "$PLATFORM_ORIGIN/miniapp/v1/apps/$APP_ID/runtime/sessions/validate" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "X-MiniApp-Session: $SESSION_KEY"

无需 JSON 请求体。成功为 HTTP 200、code=miniapp_success，data 包含 app_id、version、openid、issued_at 和 expires_at；失效响应按本接口契约处理，并重新建立登录态。

应用自己的退出流程可在撤销业务登录态后，按需吊销平台会话：

curl --request POST "$PLATFORM_ORIGIN/miniapp/v1/apps/$APP_ID/runtime/sessions/revoke" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "X-MiniApp-Session: $SESSION_KEY"

成功为 HTTP 204，无响应正文。接口 token 不能代替会话 Header；这两个应用后端接口不要求运行实例参数，也不作为每次业务请求的新增强制步骤。

安全与排错

AppSecret 位于兼容接口 Query，因此应用后端、反向代理和 APM 都不得记录完整请求 URL。反馈问题时保留请求 ID、AppID 和错误码。响应携带 X-Request-ID 且禁止缓存。

AppSecret 重置或冻结会阻止新的登录兑换；已发行 session_key 的吊销仍由应用、版本和运行实例状态管理。完整字段约束见小程序登录凭证校验。

预期结果

业务后端保存本应用 openid 和 session_key，小程序只取得业务登录结果。再次请求业务接口时使用业务自己的登录态；一次性 code 不继续使用。

常见失败

errcode 或现象	处理
40029	code 无效或过期，重新调用 wx.login
40163	code 已消费，取得新 code，不重放旧请求
40125	核对当前 AppSecret、冻结状态与应用状态
-1 或网络失败	保留请求 ID，检查依赖与网络，再重新登录
业务态存在但平台会话失效	由后端按自己的会话规则处理，必要时重新登录

下一步

按需接入手机号、隐私与功能或余额支付，然后完成体验测试。