身份与登录

四方职责

调用方	负责内容	持有材料
小程序 JS	通过 SDK 请求登录码，向自有业务后端登录	一次性 code、业务登录态
宿主	确认宿主身份、当前应用及运行实例，获取登录码，执行受控网络	宿主身份材料，不向 JS 暴露
应用后端	兑换 code、按 App ID 与 openid 识别用户，建立业务登录态	应用服务凭据、仅后端保存的平台 token
平台	签发和消费登录码，校验版本、会话与吊销状态	应用作用域身份与运行治理状态

SDK 的登录与网络调用方法以双端联调交付为准。本页说明接入协议，不宣称具体 wx.* 方法已在宿主可用。平台已删除固定登录转发入口，业务后端可自行定义登录路由。

兑换一次性登录码

前置条件：应用处于可运行状态，当前版本是 testing 或 published；testing 用户具有有效体验资格。宿主传入本次运行的 code 与 run_instance_id；登录码有效期为 5 分钟，只能消费一次。

以下请求只在应用后端执行。示例值为占位符，PLATFORM_ORIGIN 使用团队分配的环境入口。

curl --request POST "$PLATFORM_ORIGIN/miniapp/v1/apps/$APP_ID/runtime/sessions/exchange" \
  --header "Authorization: Bearer $APP_SERVICE_CREDENTIAL" \
  --header 'Content-Type: application/json' \
  --data '{"code":"<宿主本次返回的登录码>","run_instance_id":"<宿主本次运行实例>"}'

成功状态为 201，响应形状如下（时间与令牌仅为示意）：

{
  "code": "miniapp_success",
  "data": {
    "session": {
      "app_id": "<当前应用>",
      "version": "1.0.0",
      "openid": "oid_0123456789abcdef0123456789abcdef0123456789abcdef",
      "run_instance_id": "<本次运行实例>",
      "issued_at": "2026-09-08T00:00:00Z",
      "expires_at": "2026-09-09T00:00:00Z"
    },
    "token": "<仅保存在应用后端>"
  }
}

应用后端建立自己的业务登录态后返回给 JS，不能透传平台 token。openid 只在同一应用内稳定，不能用于跨应用关联用户。完整字段约束见兑换会话。

校验与退出

应用后端调用会话校验或会话吊销，同时携带服务凭据、X-MiniApp-Session 和 X-MiniApp-Run-Instance。

平台会话与应用业务登录态分别管理；平台吊销不会自动删除业务后端的自建会话。应用应在需要平台运行权限的操作中校验平台会话，并在退出、账号切换或失效后清除相应业务状态。

失败处理

• 凭据失效或应用不匹配：检查后端配置与凭据状态，不向用户索取管理员凭据。
• 登录码过期、已消费或实例不匹配：重新通过宿主取得登录码，不复用旧 code。
• 兑换请求超时：结果可能已被消费，重新开始登录；不要无限重试同一 code。
• 版本被停用或回滚：重新获取可运行版本并重新登录。

记录 X-Request-ID 供定位；不记录 code、token 或 Authorization。