Linking accounts to users

The React SDK supports linking all supported account types via our modal-guided link methods. To prompt a user to link an account, use the respective method from the useLinkAccount hook:

Method	Description	User Experience
`linkEmail`	Links email address	Opens modal
`linkPhone`	Links phone number	Opens modal
`linkWallet`	Links external wallet	Opens modal
`linkGoogle`	Links Google account	Direct redirect
`linkApple`	Links Apple account	Direct redirect
`linkTwitter`	Links Twitter account	Direct redirect
`linkDiscord`	Links Discord account	Direct redirect
`linkGithub`	Links Github account	Direct redirect
`linkLinkedIn`	Links LinkedIn account	Direct redirect
`linkTiktok`	Links TikTok account	Direct redirect
`linkSpotify`	Links Spotify account	Direct redirect
`linkInstagram`	Links Instagram account	Direct redirect
`linkTelegram`	Links Telegram account	Direct redirect
`linkFarcaster`	Links Farcaster account	Displays QR code
`linkPasskey`	Links passkey	Opens modal
`linkTwitch`	Links Twitch account	Direct redirect
`linkLine`	Links LINE account	Direct redirect
`linkOAuth`	Links additional OAuth account	Direct redirect
`linkWithCustomJwt`	Links a custom JWT account (via `useLinkJwtAccount` hook)	Headless

Users are only permitted to link a single account for a given account type, except for wallets and passkeys. Concretely, a user may link at most one email address, but can link as many wallets and passkeys as they’d like.

Sample prompt to link a user's email after they have logged in

Below is an example button for prompting a user to link an email to their account:

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

function LinkOptions() {
    const {linkEmail, linkGoogle, linkWallet} = useLinkAccount();

    return (
        <div className="link-options">
            <button onClick={linkEmail}>Link Email to user</button>
            <button onClick={linkGoogle}>Link Google account to user</button>
            <button onClick={linkWallet}>Link Wallet to user</button>
        </div>
    );
}

Callbacks

You can optionally register an onSuccess or onError callback on the useLinkAccount hook.

const {linkGoogle} = useLinkAccount({
    onSuccess: ({user, linkMethod, linkedAccount}) => {
        console.log('Linked account to user ', linkedAccount);
    },
    onError: (error) => {
        console.error('Failed to link account with error ', error)
    }
})

({user: User, linkMethod: string, linkedAccount: linkedAccount}) => void

Optional callback to run after a user successfully links an account.

(error: string) => void

Optional callback to run after there is an error during account linkage.

Looking for whitelabel link methods? Our useLoginWith<AccountType> hooks allow will link an account to a user, provided that the user is already logged in whenever the authentication flow is completed. For headless wallet linking with useLinkWithSiwe or useLinkWithSiws, see the whitelabel user management documentation.

Linking additional OAuth accounts

The linkOAuth method allows your app to link additional OAuth providers that are not natively supported by Privy. For built-in providers like Google or Twitter, use the dedicated methods (e.g., linkGoogle, linkTwitter).

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

function LinkOAuthButton() {
    const {linkOAuth} = useLinkAccount();

    return (
        <button onClick={() => linkOAuth({provider: 'custom:twitch'})}>
            Link Twitch account
        </button>
    );
}

Parameters

The linkOAuth method accepts an object with the following fields:

string

required

The additional OAuth provider to link, in the format 'custom:<provider-name>' (e.g., 'custom:twitch').

Linking passkeys

The linkPasskey method accepts an optional object with the following fields:

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

function LinkPasskeyButton() {
    const {linkPasskey} = useLinkAccount();

    return (
        <button onClick={() => linkPasskey({name: 'My Passkey'})}>
            Link a passkey
        </button>
    );
}

Parameters

string

An optional display name to associate with the passkey. This name is shown to the user in their password manager (e.g. Google Password Manager, iCloud Keychain) when selecting which passkey to use for authentication. If not provided, the passkey defaults to your app name configured in the Privy Dashboard.

Linking custom JWT accounts

If your app uses an external JWT-based authentication provider, use the useLinkJwtAccount hook to link a custom JWT account to an already-authenticated Privy user. Unlike the methods above, this hook is headless: you provide the JWT yourself and Privy verifies it on the server.

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

function LinkJwtAccountButton() {
    const {linkWithCustomJwt, state} = useLinkJwtAccount();

    const handleLink = async () => {
        const jwt = await getJwtFromExternalAuth();
        await linkWithCustomJwt(jwt);
    };

    return (
        <button onClick={handleLink} disabled={state.status === 'loading'}>
            Link external account
        </button>
    );
}

Parameters

string

required

The JWT issued by your external authentication provider to link to the user’s account.

State

The state property tracks the current state of the JWT linking flow:

Status	Description
`'initial'`	The flow has not started
`'loading'`	The JWT is being verified and linked
`'not-enabled'`	Custom JWT auth is not enabled for this app
`'done'`	The account was linked successfully
`'error'`	An error occurred

Callbacks

You can optionally pass onSuccess and onError callbacks into useLinkJwtAccount:

const {linkWithCustomJwt, state} = useLinkJwtAccount({
    onSuccess: ({user, linkMethod, linkedAccount}) => {
        console.log('JWT account linked successfully', linkedAccount);
    },
    onError: (error) => {
        console.error('Failed to link JWT account', error);
    }
});

Custom JWT authentication must be enabled in your Privy Dashboard before using this hook. See the JWT-based authentication setup docs for instructions.

Users

User management

Managing users

Migrating users to Privy

Webhooks

Linking accounts to users

Callbacks

Linking additional OAuth accounts

Parameters

Linking passkeys

Parameters

Linking custom JWT accounts

Parameters

State

Callbacks

​Callbacks

​Linking additional OAuth accounts

​Parameters

​Linking passkeys

​Parameters

​Linking custom JWT accounts

​Parameters

​State

​Callbacks

Callbacks

Linking additional OAuth accounts

Parameters

Linking passkeys

Parameters

Linking custom JWT accounts

Parameters

State

Callbacks