Unlinking accounts from users

Developers can use Privy to unlink users’ linked accounts (such as a wallet or Discord profile) at any point in their user journey. This might be useful whenever the user has either created a new external account (such as a new Twitter profile or email address) and want to remove the old linked account from their user.

​

Using an unlinked account again

Unlinking removes the association between a login method and a Privy user. It does not block that login method from being used again in the app.

When email-based account merging is enabled, Privy uses email addresses to match email, Google, and Apple accounts. When a user logs in again with an unlinked account, Privy checks whether its email matches an account still linked to an existing user. If it does, Privy re-adds the removed account and logs in that user.

Otherwise, logging in with the removed identity creates a separate user when signups are allowed. In login-only mode (no-signup), the request fails instead.

The React SDK supports unlinking all supported account types via dedicated hooks. To prompt a user to unlink an account, use the corresponding hook:

Hook	Description
useUnlinkEmail	Unlinks an email address
useUnlinkPhone	Unlinks a phone number
useUnlinkWallet	Unlinks an external wallet
useUnlinkOAuth	Unlinks an OAuth account (Google, Twitter, etc.)
useUnlinkFarcaster	Unlinks a Farcaster account
useUnlinkTelegram	Unlinks a Telegram account
useUnlinkPasskey	Unlinks a passkey

Each hook returns an unlink method that accepts an object with the relevant identifier.

Users are only permitted to unlink an account so long as they have at least one more linked account.

Below is an example button for prompting a user to unlink certain linked accounts:

import {usePrivy} from '@privy-io/react-auth';
import {useUnlinkEmail, useUnlinkWallet, useUnlinkOAuth} from '@privy-io/react-auth';

function UnlinkOptions() {
  const {user} = usePrivy();
  const {unlink: unlinkEmail} = useUnlinkEmail();
  const {unlink: unlinkWallet} = useUnlinkWallet();
  const {unlink: unlinkOAuth} = useUnlinkOAuth();

  return (
    <div className="unlink-options">
      <button onClick={() => unlinkEmail({address: '[e-mail]'})}>
        Unlink email
      </button>
      <button onClick={() => unlinkOAuth({provider: 'google', subject: 'google-subject-id'})}>
        Unlink Google account
      </button>
      <button onClick={() => unlinkWallet({address: '0x...'})}>
        Unlink wallet
      </button>
    </div>
  );
}

​

Unlinking OAuth accounts

The useUnlinkOAuth hook supports unlinking any OAuth provider, including built-in providers (e.g., 'google', 'twitter') and additional OAuth providers (e.g., 'custom:twitch').

import {usePrivy} from '@privy-io/react-auth';
import {useUnlinkOAuth} from '@privy-io/react-auth';

function UnlinkOAuthButton() {
    const {user} = usePrivy();
    const {unlink: unlinkOAuth} = useUnlinkOAuth();

    // Find the OAuth account to unlink
    const twitchAccount = user?.linkedAccounts?.find(
        (account) => account.type === 'custom:twitch'
    );

    const handleUnlink = () => {
        if (twitchAccount) {
            unlinkOAuth({
                provider: 'custom:twitch',
                subject: twitchAccount.subject
            });
        }
    };

    return (
        <button onClick={handleUnlink} disabled={!twitchAccount}>
            Unlink Twitch account
        </button>
    );
}

​

Parameters

The unlink method from useUnlinkOAuth accepts an object with the following fields:

provider · string · required

The OAuth provider to unlink. Use a built-in provider (e.g., 'google', 'twitter') or a custom provider in the format 'custom:<provider-name>' (e.g., 'custom:twitch').

subject · string · required

The provider-specific subject identifier that uniquely identifies the user for the selected OAuth provider. This can be found in the linked account’s subject field.