验证三方登录¶
请求参数¶
面向App,服务端使用PostgreSQL;dev/prod表示运行配置,不代表不同服务器。当前公网入口使用HTTPS;仅显式启用的dev固定码HTTP例外可访问隔离开发身份。任何prod组合均关闭固定码与HTTP例外,不能靠X-Forwarded-Proto绕过。
八项公共请求头全部必填;X-Client-Type只能为app,平台ios/android。成功及业务错误响应设置Cache-Control:no-store,合法请求ID回传X-Request-Id。不需要Authorization。
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
| challengeId | string(UUID) | 是 | 申请三方挑战返回的编号 |
| credential | string | 是 | Google/Apple的ID Token;微信的一次性授权码;最长16384 |
| state | string | 是 | 前一步返回的nonce,最长128 |
无路径参数和查询参数。
请求示例¶
示例账号、凭证及UUID为合成数据。当前唯一正式部署环境处于上线前阶段,dev运行配置下手机号和邮箱统一使用123456,仍须先申请challengeId,不发送短信或邮件。公网HTTPS已验收;真实发送供应商及正式开放前的配置检查仍待完成。
base_url='https://api.example.com' # 示例占位,替换为已配置HTTPS的服务入口
device_id='4d4ae3ea-6a4a-4f34-a292-8e94551851d7' # 同一安装持久保存
request_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
timestamp="$(date +%s)000"
curl -i --fail-with-body \
-X POST "$base_url/api/v1/auth/providers/login" \
-H 'Accept: application/json' \
-H 'Accept-Language: zh-CN' \
-H 'X-Client-Type: app' \
-H 'X-Platform: android' \
-H 'X-App-Version: 1.0.0' \
-H 'X-App-Build: 1' \
-H 'X-Channel: dev' \
-H "X-Device-Id: $device_id" \
-H "X-Request-Id: $request_id" \
-H "X-Request-Timestamp: $timestamp" \
-H 'Content-Type: application/json' \
--data '{"challengeId":"33333333-3333-4333-8333-333333333333","credential":"替换为官方SDK返回的凭据","state":"替换为该挑战的nonce"}'
成功响应¶
HTTP 200。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"tokenType": "Bearer",
"accessToken": "bda_<示例占位,使用实际返回值>",
"accessExpiresAt": "2026-11-03T00:15:00Z",
"refreshToken": "bdr_<示例占位,使用实际返回值>",
"refreshExpiresAt": "2026-12-03T00:00:00Z",
"userId": "11111111-1111-4111-8111-111111111111",
"registrationStatus": "INCOMPLETE",
"nextStep": "COUNTRY",
"registrationStep": 1,
"vipGateEnabled": false,
"vipActive": false,
"vipRequired": false
},
"errors": []
}
| data字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| tokenType | string | 否 | 固定Bearer |
| accessToken | string | 否 | bda_开头的256位随机访问凭证 |
| accessExpiresAt | string(date-time) | 否 | 访问过期时间,最长15分钟 |
| refreshToken | string | 否 | bdr_开头的单次刷新凭证 |
| refreshExpiresAt | string(date-time) | 否 | 会话创建后30天的绝对期限,刷新不延长 |
| userId | string(UUID) | 否 | 当前账号编号 |
| registrationStatus | string | 否 | INCOMPLETE 或 COMPLETE |
| nextStep | string | 否 | COUNTRY、PROFILE、INTRO、INTERESTS、COMPLETE_REGISTRATION 或 HOME,保留原导航语义 |
| registrationStep | integer | 否 | 仅1–4:1国家、2资料、3语言生日介绍、4兴趣;完成后仍为4,由registrationStatus区分 |
| vipGateEnabled | boolean | 否 | 当前会话发行渠道的第二层VIP准入开关,动态读取,默认false |
| vipActive | boolean | 否 | 服务端确认的有效VIP权益;未付款、过期或撤销为false |
| vipRequired | boolean | 否 | 资料完成且开关开启、无有效VIP时为true,需进入VIP页 |
失败响应¶
| HTTP | 业务码 | 条件/处理 |
|---|---|---|
| 400 | INVALID_APP_CHANNEL | 渠道未知、平台不匹配或prod误用dev,不能当关闭VIP门槛 |
| 400 | INVALID_CLIENT_HEADERS | 元数据缺失、重复或不合法 |
| 400 | VALIDATION_FAILED / BAD_REQUEST | 请求字段、类型或JSON不符合契约 |
| 403 | FORBIDDEN | 本批仅接受app类型客户端 |
| 503 | SERVICE_UNAVAILABLE | 当前渠道VIP策略缺失或数据库暂不可用;不按关闭门槛放行 |
| 426 | HTTPS_REQUIRED | 敏感接口要求HTTPS |
| 401 | AUTH_PROVIDER_INVALID | 凭据、state、nonce、签名、受众等无效或已使用 |
| 403 | ACCOUNT_DISABLED | 账号不可用 |
| 409 | CONSENT_VERSION_CHANGED | 重新同意协议 |
| 429 | AUTH_RATE_LIMITED | 请求过于频繁 |
| 503 | AUTH_PROVIDER_UNAVAILABLE | 未配置渠道或供应商暂不可达 |
错误结构与公共协议一致;字段校验使用errors[].field/message,Accept明确不接受可用响应格式时406可无正文。示意:
{
"code": "AUTH_PROVIDER_INVALID",
"message": "对应当前请求语言的错误提示",
"data": null,
"errors": []
}
接入说明¶
VIP开关按发行渠道独立读取,沿用既有X-Channel/X-Platform及三个VIP布尔字段。登录绑定会话渠道,访问和刷新须一致;历史NULL会话首次合法使用绑定,之后改头返回401。账号渠道字段缺失时,本次认证成功后自动补录;已有值不覆盖,补录不代表还原历史注册来源。普通Bearer认证请求同样适用,无需新增请求,完整规则见公共请求头。该字段只供展示,不决定当前会话门槛。详见渠道与VIP准入。
两层跳转与支付边界见注册资料与VIP准入:先完成资料,再判断vipRequired;COMPLETE或nextStep=HOME单独都不足以跳过开启的VIP门槛。渠道开关独立配置(首次初始化默认关闭,升级保留原值),客户端不能自行提交付款成功来获得权益。
步骤对应与重登恢复流程见登录注册步骤说明。每次保存资料成功后由服务端同步落库,登录直接返回registrationStep供前端跳转,无需增加或调用单独进度接口;现有刷新和本人资料也返回同一字段,客户端不提交步骤。第4步及已完成用户均返回4,registrationStatus=COMPLETE后还须判断vipRequired:true进入VIP页,false才进入首页。
当前固定验证码模式不启用真实三方登录,两个三方接口均返回AUTH_PROVIDER_UNAVAILABLE。后续关闭固定模式并配置对应供应商再联调。
Google/Apple验证官方签名、签发者、应用受众、过期及nonce;微信由服务端向官方接口兑换授权码。微信主体按AppID+OpenID隔离。请求不能提供 userId、openid 或 email 代替验证。不同供应商身份不会仅因邮箱相同自动合并,已有账号的换绑/合并接口未包含在本批。每挑战最多5次校验尝试,成功一次后失效;每小时安装60次、直连IP150次。
验证:在服务器隔离PostgreSQL上验证认证、字段校验与失败分支;验证码投递使用仅测试源码中的捕获替身,Google/Apple使用临时RSA密钥完成真实验签测试。未向真实用户发送短信/邮件,未使用真实三方应用完成端到端登录,也未代表Flutter已接入。接口实现位于Java的identity/profile/catalog/media模块;完整接入顺序见登录注册接入。