Skip to main content

Bind Third-Party Account

POST 
/auth/v1/user/provider/bind

API Description​

Bind third-party account API, used to bind third-party identity sources (such as GitHub, WeChat, QQ, etc.) to the current logged-in user account, enabling multiple login methods.

Input Requirements​

Required Parameters​

  • provider_token: Third-party identity source token (required, obtained through /auth/v1/provider/token API)
  • Authorization: Current logged-in user's access_token (required, passed in request header, format Bearer xxx)

Optional Parameters​

  • with_user_center: Whether to record in user centralized security log (optional, boolean, default false)
  • client_id: Client ID (optional, defaults to environment ID)
  • x-device-id: Device ID (optional, passed in request header)

Prerequisites​

  • User must be logged in (need valid access_token)
  • User must complete authorization on third-party platform
  • Must call Get Third-Party Authorization Info API to obtain provider_token
  • The third-party account cannot already be bound by other users

Output Description​

Successful Response​

  • Returns empty object {}, indicating successful binding

Request Example​

Bind GitHub Account Request Example​

{
  "provider_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm92aWRlciI6ImdpdGh1YiIsInN1YiI6IjEyMzQ1Njc4OTAiLCJleHAiOjE3MzQ2ODIzNTd9.bVJ0cE1xTnBWc0R5QmhKa0xmR3pYY1ZiTm1Bc1FkRmdIaktsTXBPclN0VXZXeElaQWJDZERlRmZHaEhpSmpLa0xs",
  "with_user_center": true
}

Response Examples​

Binding Success Response Example​

{}

Provider Token Invalid Response Example​

{
  "error": "invalid_grant",
  "error_code": 4001,
  "error_description": "Provider token invalid or expired"
}

Not Logged In Response Example​

{
  "error": "unauthorized",
  "error_code": 4003,
  "error_description": "User not logged in or access_token invalid"
}

Field Description​

Request Parameters​

Field NameTypeRequiredDescription
provider_tokenstringYesThird-party identity source token, obtained through /auth/v1/provider/token API
with_user_centerbooleanNoWhether to record in user centralized security log, default false
client_idstringNoClient ID, defaults to environment ID
x-device-idstringNoDevice ID, passed in request header
AuthorizationstringYesCurrent logged-in user's access_token, format Bearer xxx, passed in request header

Response Parameters​

Field NameTypeRequiredDescription
-objectYesReturns empty object {} on success

Usage Flow​

Complete Binding Flow​

1. User Login​

  • User must first login to system
  • Obtain valid access_token

2. Get Authorization URL​

  • Call Get Third-Party Login Callback URL API (optional, depends on third-party platform authorization flow)
  • Get third-party authorization URL
  • Open authorization page in new window or popup

3. User Authorization​

  • User completes authorization on third-party platform
  • Third-party platform callbacks and returns authorization code

4. Get Provider Token​

5. Bind Account​

  • Call this API
  • Pass provider_token and access_token
  • Complete account binding

Core Features​

Multiple Account Binding​

  • Supports binding multiple third-party identity sources
  • Same user can bind GitHub, WeChat, QQ and other accounts
  • Can login using any bound method after binding
  • Supports unbinding anytime

Security​

  • Requires user login status
  • Use within provider_token validity period
  • Prevents duplicate binding
  • Records binding logs

Flexibility​

  • Supports multiple identity sources
  • Supports custom identity sources
  • Supports security log recording
  • Supports device management

Usage Scenarios​

Account Binding​

  • User binds third-party account in personal settings
  • Convenient to login using multiple methods
  • Enhances account security

Social Account Association​

  • Bind GitHub account
  • Bind WeChat account
  • Bind QQ account
  • Bind Weibo account

Enterprise Account Association​

  • Bind Enterprise WeChat account
  • Bind DingTalk account
  • Bind Feishu account

Notes​

Account Binding Restrictions​

  • Same third-party account can only bind one user
  • Same user can bind multiple different third-party accounts
  • Cannot bind third-party account already bound by other users
  • Checks for existing binding relationship before binding

Access Token​

  • Must be valid access_token
  • Must be passed in request header
  • Format must be Bearer xxx
  • Need to re-login when token expires

Unbinding Operation​

Error Handling​

Common Errors​

  • invalid_grant: Provider token invalid or expired
  • unauthorized: User not logged in or access_token invalid

Error Handling Strategy​

  • provider_token invalid: Re-obtain authorization
  • Account already bound: Prompt user that account is already in use
  • Not logged in: Redirect to login page
  • Identity source not configured: Contact administrator
  • Reached binding limit: Unbind infrequently used accounts

Request​

Query Parameters

    client_id string

    Client ID corresponding to the application, can be obtained from Cloud Development Platform -> Identity Authentication -> Development Settings. Defaults to environment ID, can be omitted

Header Parameters

    x-device-id string

    Device ID, the ID of the current logged-in device. The client should generate it randomly and cache it on the client. This parameter is related to the number of logged-in accounts.

    Authorization stringrequired

    The access_token of the current logged-in user, format is Bearer xxx

    Example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ

Body

    provider_token string

    Third-party identity source provider_token, obtained from /auth/v1/provider/token

    with_user_center boolean

    Whether to record in the user centralized security log

Responses​

A successful response.

Response Headers
    Schema
      any
    Loading...