POST/api/v1/auth/linked-accounts绑定一个三方身份

Try it 面板需要启用 JavaScript。

以三方授权码为已登录用户绑定新的三方身份。

Request

Headers

Name	Data Type	Required	Description
Authorization	string	Yes	会话令牌认证，格式 `Bearer <sessionToken>`
Content-Type	string	Yes	请求体内容类型（默认值 "application/json"）

type RequestHeaders = {
  /** 会话令牌认证，格式 `Bearer <sessionToken>` */
  Authorization: string
  /** 请求体内容类型，默认值 "application/json" */
  Content-Type: string
}

{
  "Authorization": "Bearer st_7c1f9e05b28d4a63",
  "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": "google",
  "authorizationCode": "4/0AX4XfWht9VhKzMqB",
  "redirectUri": "https://passport.xeegam.com/callback/google"
}

Response

Body

LinkedAccountDTO

Name	Data Type	Required	Description
linkId	string	Yes	绑定关系 ID
provider	string	Yes	提供方：google / apple / github
providerAccountId	string	Yes	提供方账号标识（脱敏展示）
linkedAt	string	Yes	绑定时间（ISO 8601 UTC）

type LinkedAccountDTO = {
  /** 绑定关系 ID */
  linkId: string
  /** 提供方：google / apple / github */
  provider: string
  /** 提供方账号标识（脱敏展示） */
  providerAccountId: string
  /** 绑定时间（ISO 8601 UTC） */
  linkedAt: string
}

{
  "linkId": "01JD8SF01P4M8W2XK6Q9VDH3T5B",
  "provider": "github",
  "providerAccountId": "gh_u***2847",
  "linkedAt": "2026-10-14T08:30:00Z"
}

HTTP Code

HTTP Status	Meaning	Notes
200	成功	返回新绑定
400	三方授权无效	授权码校验失败
409	已绑定	该三方身份已绑定到其他用户

Response Code

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

code	Meaning	Notes
0	成功	返回新绑定
2004	三方授权无效	授权码校验失败或 redirectUri 不匹配
2011	已绑定该三方	当前用户已绑定同提供方的一个身份
2012	三方账号已被他人绑定	该三方身份属于其他用户

Examples

POST /api/v1/auth/linked-accounts
Authorization: Bearer st_7c1f9e05b28d4a63
Content-Type: application/json

{
  "provider": "google",
  "authorizationCode": "4/0AX4XfWht9VhKzMqB",
  "redirectUri": "https://passport.xeegam.com/callback/google"
}

{
  "id": "01JD8SHFC0N7M1H0",
  "code": 0,
  "messages": [],
  "result": {
    "linkId": "01JD8SF02Q5N9W3XL7R0WDI4U6C",
    "provider": "google",
    "providerAccountId": "g_***5183",
    "linkedAt": "2026-10-14T10:00:00Z"
  }
}