Account Linking

gau allows users to connect multiple OAuth providers (e.g., GitHub and Google) to a single user account. This provides a seamless experience, allowing them to sign in with any of their linked providers to access the same account.

This can be done in two ways:

Automatic Linking: gau can automatically link accounts based on a shared, verified email address when a user signs in.
Manual Linking: Authenticated users can manually link or unlink providers from their account settings page.

Automatic Account Linking

gau has an automatic account linking feature, configured via the autoLink option in createAuth.

When an existing user signs in with a new provider, gau can automatically associate this new sign-in with their existing account.

How It Works

Check for Existing Account: When a user signs in, gau first checks if an account already exists for that user with the specific OAuth provider. If so, it logs them in.
Check for Email to Link: If no account is found for that provider, gau looks at the email address returned by the new OAuth provider. It then checks if any user in your database already has that same email address.
Link or Create:
- If a user with that email already exists, gau will link the new OAuth sign-in to that existing user record.
- If no user with that email is found, a new user is created.

This means a user can sign in with GitHub, sign out, and then sign back in with Google, and they will be logged into the same account, as long as both services use the same verified email address.

Configuration

You can control this behavior with the autoLink option in createAuth.

'verifiedEmail' (Default): Only links if the new provider’s email is verified.
'always': Links if emails match, even if not verified.
false: No auto-linking. Each new provider creates a new user.

Manual Account Linking

In addition to automatic linking, gau provides functions for users to manually manage their linked accounts, for example from a profile or settings page.

The useAuth hook (available in client integrations) exposes linkAccount and unlinkAccount functions.

Configuration

You can control manual linking behavior with the allowDifferentEmails and updateUserInfoOnLink options in createAuth.

`linkAccount`

This function initiates the OAuth flow to connect an additional provider to the currently logged-in user’s account.

SvelteKit
SolidStart

<script>
  import { useAuth } from '@rttnd/gau/client/svelte'
  const auth = useAuth()
</script>

<button onclick={() => auth.linkAccount('google')}>
  Connect Google Account
</button>

import { useAuth } from '@rttnd/gau/client/solid'

export function LinkButton() {
  const { linkAccount } = useAuth()

  return (
    <button onClick={() => linkAccount('google')}>
      Connect Google Account
    </button>
  )
}

`unlinkAccount`

This function removes a linked provider from the user’s account.

SvelteKit
SolidStart

<script>
  import { useAuth } from '@rttnd/gau/client/svelte'
  const auth = useAuth()
</script>

<button onclick={() => auth.unlinkAccount('google')}>
  Disconnect Google Account
</button>

import { useAuth } from '@rttnd/gau/client/solid'

export function UnlinkButton() {
  const { unlinkAccount } = useAuth()

  return (
    <button onClick={() => unlinkAccount('google')}>
      Disconnect Google Account
    </button>
  )
}

gau prevents users from unlinking their last remaining account.