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.
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:
Callbacks
You can optionally register an onSuccess
or onError
callback on the useLinkAccount
hook.
Optional callback to run after a user successfully links an account.
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 |
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:
Callbacks
You can optionally register an onSuccess
or onError
callback on the useLinkAccount
hook.
Optional callback to run after a user successfully links an account.
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.
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
.
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.
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:
Link With Code
Then, prompt the user for the code they received and use the linkWithCode
method:
The one-time passcode sent to the user’s email address.
(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
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
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:
Link With Code
Then, prompt the user for the code they received and use the linkWithCode
method:
The one-time passcode sent to the user’s email address.
The user’s email address.
Returns
Nothing, indicating success.
Throws
An error if linking the account is unsuccessful.