POST/api/v1/auth/providers/challenges
匿名,需公共头JSON 响应接入指南 ↗

申请三方登录挑战

请求参数

面向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。

字段 类型 必填 约束
provider string 是 google、apple 或 wechat
agreed boolean 是 必须为true,用户明确勾选协议
termsVersion string 是 当前用户协议版本,最长64
privacyVersion string 是 当前隐私政策版本,最长64

无路径参数和查询参数。

请求示例

示例账号、凭证及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/challenges" \
  -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 '{"provider":"google","agreed":true,"termsVersion":"2026-11-02-draft","privacyVersion":"2026-11-02-draft"}'

成功响应

HTTP 200。

{
  "code": "SUCCESS",
  "message": "操作成功。",
  "data": {
    "challengeId": "33333333-3333-4333-8333-333333333333",
    "nonce": "bdo_<随机值占位>",
    "expiresAt": "2026-11-03T00:05:00Z"
  },
  "errors": []
}
data字段 类型 可空 说明
challengeId string(UUID) 否 设备绑定的一次性挑战
nonce string 否 随机挑战值,SDK与验证接口必须关联同一次请求
expiresAt string(date-time) 否 5分钟有效期

失败响应

HTTP 业务码 条件/处理
400 INVALID_APP_CHANNEL 渠道未知、平台不匹配或prod误用dev,不能当关闭VIP门槛
400 INVALID_CLIENT_HEADERS 元数据缺失、重复或不合法
400 VALIDATION_FAILED / BAD_REQUEST 请求字段、类型或JSON不符合契约
403 FORBIDDEN 本批仅接受app类型客户端
426 HTTPS_REQUIRED 敏感接口要求HTTPS
409 CONSENT_VERSION_CHANGED 协议需要重新同意
429 AUTH_RATE_LIMITED 请求过于频繁
503 AUTH_PROVIDER_UNAVAILABLE 该三方渠道未开通配置

错误结构与公共协议一致;字段校验使用errors[].field/message,Accept明确不接受可用响应格式时406可无正文。示意:

{
  "code": "CONSENT_VERSION_CHANGED",
  "message": "对应当前请求语言的错误提示",
  "data": null,
  "errors": []
}

接入说明

VIP开关按发行渠道独立读取,沿用既有X-Channel/X-Platform及三个VIP布尔字段。登录绑定会话渠道,访问和刷新须一致;历史NULL会话首次合法使用绑定,之后改头返回401。首次注册来源字段只做归因,不决定当前会话门槛。详见渠道与VIP准入。

当前固定验证码模式不启用真实三方登录,两个三方接口均返回AUTH_PROVIDER_UNAVAILABLE。后续关闭固定模式并配置对应供应商再联调。

Google/Apple 原生SDK请求的 nonce 必须等于本次返回值,最终 ID Token 的 nonce 声明必须原样匹配;不要在客户端额外重复哈希。微信 SDK 使用该值作为 state,并校验回调 state。下一步调用三方登录验证时 state 也传回该值。每小时每安装30次、直连IP100次;未配置官方应用标识和凭据时返回不可用。

验证:在服务器隔离PostgreSQL上验证认证、字段校验与失败分支;验证码投递使用仅测试源码中的捕获替身,Google/Apple使用临时RSA密钥完成真实验签测试。未向真实用户发送短信/邮件,未使用真实三方应用完成端到端登录,也未代表Flutter已接入。接口实现位于Java的identity/profile/catalog/media模块;完整接入顺序见登录注册接入。