Linking accounts to users

Developers can use Privy to prompt users to link additional accounts (such as a wallet or Discord profile) at any point in their user journey, not just during login.

This is key to Privy’s progressive onboarding: improving conversion and UX by requiring users to complete onboarding steps (e.g. connecting an account) only when necessary.

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

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.

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)
    }
})

onSuccess

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

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

onError

(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.

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

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)
    }
})

onSuccess

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

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

onError

(error: string) => void

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

To prompt a user to link an account, use the respective hooks:

Account type	Description	Hook to invoke
`Email`	Links email address	`useLinkEmail`
`Phone`	Links phone number	`useLinkSms`
`Wallet`	Links external wallet	`useLinkWithSiwe`, `useLinkWithSiws`
`Google`	Links Google account	`useLinkWithOAuth`
`Apple`	Links Apple account	`useLinkWithOAuth`
`Twitter`	Links Twitter account	`useLinkWithOAuth`
`Discord`	Links Discord account	`useLinkWithOAuth`
`Github`	Links Github account	`useLinkWithOAuth`
`LinkedIn`	Links LinkedIn account	`useLinkWithOAuth`
`TikTok`	Links TikTok account	`useLinkWithOAuth`
`Spotify`	Links Spotify account	`useLinkWithOAuth`
`Instagram`	Links Instagram account	`useLinkWithOAuth`
`Telegram`	Links Telegram account	`useLinkWithOAuth`
`Farcaster`	Links Farcaster account	`useLinkWithFarcaster`
`Passkey`	Links passkey	`useLinkPasskey`

The steps to implementing the link flows are analogous to the login hooks useLoginWith<AccountType.

To prompt a user to link an account, use the respective methods:

Account type	Description	Method
`EmailAccount`	Links email address	`linkWithCode`

The steps to implementing the linkWithCode flow are analogous to the loginWithCode flow.

First, prompt the user for their email address and use the Privy client’s privy.email.sendCode method to send them a one-time passcode:

sendCode(email: String): Result<Unit>

Link With Code

Then, prompt the user for the code they received and use the linkWithCode method:

linkWithCode(code: String, email: String? = null): Result<Unit>

code

String

required

The one-time passcode sent to the user’s email address.

String

(Optional) The user’s email address. Though this parameter is optional, it is highly recommended that you pass the user’s email address explicitly. If email is omitted, the email from sendCode will be used.

Returns

Result<Unit>

A Result object that indicates whether the operation was successful. Returns Result.success if the email account was linked successfully, or Result.failure if there was an error.

Usage

// Send code to user's email
val sendResult: Result<Unit> = privy.email.sendCode(email = "[email protected]")

sendResult.fold(
    onSuccess = {
        // OTP was successfully sent, now prompt user for code
    },
    onFailure = {
        println("Error sending OTP: ${it.message}")
    }
)

// Link the email using the code
val linkResult: Result<Unit> = privy.email.linkWithCode(code = "123456", email = "[email protected]")

linkResult.fold(
    onSuccess = {
        println("Email successfully linked!")
        // User linked email
    },
    onFailure = {
        println("Error linking email: ${it.message}")
    }
)

To prompt a user to link an account, use the respective methods:

Account type	Description	Method
`EmailAccount`	Links email address	`linkWithCode`

The steps to implementing the linkWithCode flow are analogous to the loginWithCode flow.

First, prompt the user for their email address and use the Privy client’s privy.email.sendCode method to send them a one-time passcode:

sendCode(to email: String) async throws

Link With Code

Then, prompt the user for the code they received and use the linkWithCode method:

linkWithCode(_ code: String, sentTo email: String) async throws

code

String

required

The one-time passcode sent to the user’s email address.

sentTo

String

required

The user’s email address.

Returns

Nothing, indicating success.

Throws

An error if linking the account is unsuccessful.

Usage

// Send code to user's email
do {
    try await privy.email.sendCode(to: "[email protected]")
    // successfully sent code to users email
} catch {
    print("error sending code to \(email): \(error)")
}

// Link the email using the code
do {
    try await privy.email.linkWithCode("123456", sentTo: "[email protected]")
    print("Email successfully linked!")
    // user has linked their email!
} catch {
    print("error linking email: \(error)")
}

Migrating users to Privy

Users

Managing users

Webhooks

Linking accounts to users

Callbacks

Callbacks

Link With Code

Returns

Usage

Link With Code

Returns

Throws

Usage

Migrating users to Privy

Users

Managing users

Webhooks

​Callbacks

​Callbacks

​Link With Code

​Returns

​Usage

​Link With Code

​Returns

​Throws

​Usage

Callbacks

Callbacks

Link With Code

Returns

Usage

Link With Code

Returns

Throws

Usage