Let a signed-in user connect Google, GitHub, or another social identity.
Account settings
Better Auth · Module
linkSocial
authClient.linkSocial links an additional social or OAuth provider to the signed-in user's existing Better Auth account. It can redirect through OAuth, request extra scopes, or use provider ID tokens directly.
How it works
Call this client method while the user is signed in to begin an OAuth flow for an additional social provider. After the provider confirms the connection, Better Auth associates that provider with the existing user account and redirects to the supplied callback URL.
Syntax
await authClient.linkSocial({ provider, callbackURL?, scopes?, idToken? });Parameters
| Name | Type | Description |
|---|---|---|
provider | string | Social provider identifier to link, for example google. |
callbackURL | string, optional | URL to visit after linking completes. |
scopes | string[], optional | Additional provider scopes to request. |
idToken | object, optional | Provider token payload for direct linking; the ID token is required, while nonce, access, and refresh tokens may be optional depending on the provider. |
Returns
The page documents the linking operation and redirect flow but does not state a standalone return type.
Key points
- Client applications start the linking operation with
authClient.linkSocial. - The provider field selects which configured social identity should be connected, such as Google.
- Set callbackURL to control the destination after the provider finishes the linking flow.
- Use scopes when the application needs permissions beyond the provider's default authentication scopes.
- The API supports a token-based linking path that avoids sending the user through a provider redirect.
Common mistakes
- The provider must confirm the user's email as verified before Better Auth can connect the social account to the existing user.
- Requesting extra permissions can start another OAuth flow, so scope changes should be handled as an explicit reauthorization step.
Example: Link a Google account
import { authClient } from "@/lib/auth-client";
await authClient.linkSocial({
provider: "google",
callbackURL: "/settings",
});Starts the Google OAuth flow and returns the user to the settings page after linking.
When to use it
Reauthorize a linked provider with additional scopes for an API integration.
Permission expansion
Attach an identity using an ID token when the provider supports direct token verification.
Native provider sign-in
Interview questions
QWhat does linkSocial do?
It links an OAuth or social-provider identity to the currently authenticated user's account. The client method is authClient.linkSocial, and it accepts a provider identifier plus optional redirect and scope settings.
Follow-up: How would you link an account from server code? Use auth.api.linkSocialAccount with the provider in the request body and pass headers containing the user's session token.
QWhich options are commonly passed to linkSocial?
The provider value identifies the social provider to connect, while callbackURL controls where the browser goes after linking. scopes can request additional provider permissions.
Follow-up: What should be checked when adding scopes? Confirm that the provider supports the requested scopes and that the resulting consent flow is appropriate for the application.
QWhat conditions allow a social account to be linked?
Account linking is enabled by default. A social account can be connected when the provider confirms the email as verified, allowing multiple authentication methods to belong to one Better Auth account.
Follow-up: What is an alternative to redirect-based linking? The documentation also describes linking with provider ID tokens, but the token must be valid and the provider must support ID-token verification.
Related
signIn.socialauth.api.linkSocialAccountsocialProvidersGeneric OAuth PluginAccount linking