POST/api/v1/auth/login/third-partyGoogle / Apple / GitHub 三方登录

Try it 面板需要启用 JavaScript。

以三方授权码换取三方身份。已绑定的用户直接计入因素；未绑定的手机/邮箱匹配到已有账号时自动绑定并继续，完全陌生的三方身份则注册新账号并直接签发会话。

Request

Headers

Name	Data Type	Required	Description
Content-Type	string	Yes	请求体内容类型（默认值 "application/json"）

type RequestHeaders = {
  /** 请求体内容类型，默认值 "application/json" */
  Content-Type: string
}

{
  "Content-Type": "application/json"
}

Body

Name	Data Type	Required	Description
provider	string	Yes	提供方：google / apple / github
authorizationCode	string	Yes	三方 OAuth 授权码
redirectUri	string	Yes	回调地址，须与三方应用配置一致

type RequestBody = {
  /** 提供方：google / apple / github */
  provider: string
  /** 三方 OAuth 授权码 */
  authorizationCode: string
  /** 回调地址，须与三方应用配置一致 */
  redirectUri: string
}

{
  "provider": "github",
  "authorizationCode": "gho_16C7e42F292c6912E7710c838347Ae178B4",
  "redirectUri": "https://passport.xeegam.com/callback/github"
}

Response

Body

LoginResultDTO

Name	Data Type	Required	Description
status	string	Yes	pending 未达标 / satisfied 已达标并签发会话
attemptTicket	string	No	尝试工单；pending 时必返，后续因素验证继续携带
nextFactors	array	No	pending 时按配置仍可选的因素
sessionToken	string	No	会话令牌（不透明）；satisfied 时返回
refreshToken	string	No	刷新令牌；satisfied 时返回
sessionId	string	No	会话 ID；satisfied 时返回
expiresAt	string	No	会话过期时间；satisfied 时返回

type LoginResultDTO = {
  /** pending 未达标 / satisfied 已达标并签发会话 */
  status: string
  /** 尝试工单；pending 时必返，后续因素验证继续携带 */
  attemptTicket?: string
  /** pending 时按配置仍可选的因素 */
  nextFactors?: string[]
  /** 会话令牌（不透明）；satisfied 时返回 */
  sessionToken?: string
  /** 刷新令牌；satisfied 时返回 */
  refreshToken?: string
  /** 会话 ID；satisfied 时返回 */
  sessionId?: string
  /** 会话过期时间；satisfied 时返回 */
  expiresAt?: string
}

{
  "status": "pending",
  "attemptTicket": "atk_9f2c7be14d0a53e8",
  "nextFactors": [
    "otp",
    "mfa",
    "captcha"
  ]
}

HTTP Code

HTTP Status	Meaning	Notes
200	成功	三方因素计入尝试；达标即签发会话
400	三方授权无效	授权码错误、过期或 redirectUri 不符
403	账号被冻结	管理员已冻结该账号

Response Code

响应使用统一信封 {id, code, messages, result}，其 code 字段：

code	Meaning	Notes
0	成功	返回登录结果
2002	账号被冻结	管理员已冻结该账号
2004	三方授权无效	授权码校验失败或 redirectUri 不匹配
2012	三方账号已被他人绑定	该三方身份已绑定到其他用户

Examples

POST /api/v1/auth/login/third-party
Content-Type: application/json

{
  "provider": "github",
  "authorizationCode": "gho_16C7e42F292c6912E7710c838347Ae178B4",
  "redirectUri": "https://passport.xeegam.com/callback/github"
}

{
  "id": "01JD8SH4R9N6M0WZ",
  "code": 0,
  "messages": [],
  "result": {
    "status": "satisfied",
    "sessionToken": "st_7c1f9e05b28d4a63",
    "refreshToken": "rt_46a9c7e015283d5b",
    "sessionId": "01JD8SEGVK6MZ7W3Q4RT5N8YB2",
    "expiresAt": "2026-11-13T08:00:00Z"
  }
}

Remarks

三方因素分值同 MFA（默认 60 分），由 attempt 配置管理；新建账号场景不产生登录尝试记录。