Appearance
Documentation / react-auth / PrivyInterface
Interface: PrivyInterface ​
Allows you to manage the user's current authentication state and access their linked accounts. You can access the fields and methods documented here via the usePrivy hook.
Properties ​
authenticated ​
authenticated:
boolean
True if the user is authenticated, false otherwise.
You should always check that ready is true before using this value. Otherwise, the value may outdated while the Privy client fetches fresh tokens.
cancel ​
cancel: () =>
void
Cancel the MFA flow for the current user. If there is no pending MFA verification, this function is a no-op.
Call this method instead of submit when a user has been prompted for MFA but decides to exit the flow.
Returns ​
void
void.
connectOrCreateWallet ​
connectOrCreateWallet: () =>
void
Opens the Privy login modal and prompts the user to login or connect a wallet.
Returns ​
void
connectWallet ​
connectWallet: (
options?) =>void
Opens the Privy modal and prompts the user to connect a wallet.
Parameters ​
• options?: ExternalConnectWalletModalOptions | MouseEvent<any, any>
Returns ​
void
createWallet ​
createWallet: (
options?) =>Promise<Wallet>
Creates an embedded wallet for the current user.
This method will error if the user already has an embedded wallet or if they exit in the middle of the flow.
If the config.embeddedWallets.requireUserOwnedRecoveryOnCreate property is set to true, this will prompt the user to complete a recovery flow to secure the recovery share of their embedded wallet.
Otherwise (the default), Privy will secure the recovery share, and the embedded wallet will be created without showing any UIs to the user.
Parameters ​
• options?: MouseEvent<any, any> | CreateWalletOptions
Returns ​
Promise<Wallet>
Promise for the Wallet object for the newly created embedded wallet
enrollInMfa ​
enrollInMfa: (
show?) =>void
Function to control the visibility of the enrollment modal.
Parameters ​
• show?: boolean
{boolean} controls the visibility of the enrollment modal.
Returns ​
void
Promise for opening the enrollment modal.
exportWallet ​
exportWallet: (
options?) =>Promise<void>
Shows the user a Privy modal, from which they can copy their Ethereum embedded wallet's private key or seed phrase for easy export to another wallet client (e.g. MetaMask). The private key is loaded on an iframe running on a separate domain from your app, meaning your app cannot access it.
This method will error if the user is not authenticated or does not have an embedded wallet.
Parameters ​
• options?: MouseEvent<any, any> | Object
{address: string} (optional) Ethereum wallet address to export the private key for
Returns ​
Promise<void>
Promise that resolves once the user exits the modal
getAccessToken ​
getAccessToken: () =>
Promise<null|string>
Get the Privy access token (JWT) for an authenticated user. Returns null for an unauthenticated user.
You may use this token to authorize requests sent from your frontend, and can validate it in your backend against your app's Privy verification key.
This will automatically attempt to refresh the session if the token is expired or about to expire.
Returns ​
Promise<null | string>
Promise for the user's access token as a string if they are authenticated, null if they are unauthenticated.
init ​
init: (
mfaMethod) =>Promise<void|PublicKeyCredentialRequestOptionsJSON>
Initiate the MFA flow for the current user.
Parameters ​
• mfaMethod: "sms" | "totp" | "passkey"
MfaMethod The available MFA method to trigger for the current user.
Returns ​
Promise<void | PublicKeyCredentialRequestOptionsJSON>
Promise for sending the MFA code to the user's device.
initEnrollmentWithPasskey ​
initEnrollmentWithPasskey: () =>
Promise<void>
Initiate the enrollment flow for Passkey MFA for the current user.
Returns ​
Promise<void>
void The TOTP Auth Url is used to encode into a QR Code for the user to scane.
initEnrollmentWithSms ​
initEnrollmentWithSms: (
meta) =>Promise<void>
Initiate the enrollment flow for MFA for the current user.
Parameters ​
• meta: Object
{phoneNumber: string} The meta data needed to complete the MFA flow.
• meta.phoneNumber: string
Returns ​
Promise<void>
Promise for enrolling the current user with the chosen MFA method.
initEnrollmentWithTotp ​
initEnrollmentWithTotp: () =>
Promise<Object>
Initiate the enrollment flow for TOTP MFA for the current user.
Returns ​
Promise<Object>
{secret: string; authUrl: string} The TOTP Auth Url is used to encode into a QR Code for the user to scane.
authUrl ​
authUrl:
stringsecret ​
secret:
string
isModalOpen ​
isModalOpen:
boolean
Check whether the Privy Modal is visible.
linkApple ​
linkApple: () =>
void
For users who are authenticated, prompts the user to link Apple OAuth account This will directly initiate the OAuth flow for Apple.
Returns ​
void
linkDiscord ​
linkDiscord: () =>
void
For users who are authenticated, prompts the user to link Discord OAuth account This will directly initiate the OAuth flow for Discord.
Returns ​
void
linkEmail ​
linkEmail: () =>
void
For users who are authenticated, opens the Privy modal and prompts the user to link an email. This will open the Privy Modal which will guide the user through this action.
Returns ​
void
linkFarcaster ​
linkFarcaster: () =>
void
For users who are authenticated, opens the Privy modal and prompts the user to link a Farcaster account. This will open the Privy Modal which will guide the user through this action.
Returns ​
void
linkGithub ​
linkGithub: () =>
void
For users who are authenticated, prompts the user to link Github OAuth account This will directly initiate the OAuth flow for Github.
Returns ​
void
linkGoogle ​
linkGoogle: () =>
void
For users who are authenticated, prompts the user to link a Google OAuth account. This will directly initiate the OAuth flow for Google.
Returns ​
void
linkInstagram ​
linkInstagram: () =>
void
For users who are authenticated, prompts the user to link Instagram OAuth account This will directly initiate the OAuth flow for Instagram.
Returns ​
void
linkLinkedIn ​
linkLinkedIn: () =>
void
For users who are authenticated, prompts the user to link LinkedIn OAuth account This will directly initiate the OAuth flow for LinkedIn.
Returns ​
void
linkPasskey ​
linkPasskey: () =>
void
For users who are authenticated, prompts the user to link a Passkey account This will open the Privy Modal which will guide the user through this action.
Returns ​
void
linkPhone ​
linkPhone: () =>
void
For users who are authenticated, opens the Privy modal and prompts the user to link a phone number. This will open the Privy Modal which will guide the user through this action.
Returns ​
void
linkSpotify ​
linkSpotify: () =>
void
For users who are authenticated, prompts the user to link Spotify OAuth account This will directly initiate the OAuth flow for Spotify.
Returns ​
void
linkTelegram ​
linkTelegram: (
options?) =>void
For users who are authenticated, prompts the user to link a Telegram account This will directly initiate the auth flow for Telegram.
Parameters ​
• options?: Object
• options.launchParams?: Object
• options.launchParams.initDataRaw?: string
Returns ​
void
linkTiktok ​
linkTiktok: () =>
void
For users who are authenticated, prompts the user to link Tiktok OAuth account This will directly initiate the OAuth flow for Tiktok.
Returns ​
void
linkTwitter ​
linkTwitter: () =>
void
For users who are authenticated, prompts the user to link a Twitter OAuth account This will directly initiate the OAuth flow for Twitter.
Returns ​
void
linkWallet ​
linkWallet: (
options?) =>void
For users who are authenticated, opens the Privy modal and prompts the user to link a wallet. This will open the Privy Modal which will guide the user through this action.
Parameters ​
• options?: ExternalConnectWalletModalOptions | MouseEvent<any, any>
Returns ​
void
login ​
login: (
options?) =>void
Opens the Privy login modal and prompts the user to login.
Parameters ​
• options?: MouseEvent<any, any> | LoginModalOptions
Returns ​
void
logout ​
logout: () =>
Promise<void>
Log the current user out and clears their authentication state. authenticated will become false, user will become null, and the Privy Auth tokens will be deleted from the browser's local storage.
You may await this call to take an action once logout is complete (e.g. redirecting to a specific page).
Returns ​
Promise<void>
mfaMethods ​
mfaMethods: (
"sms"|"totp"|"passkey")[]
The available mfa methods of this App
promptMfa ​
promptMfa: () =>
Promise<void>
Triggers the MFA verification flow if the user has an MFA method enrolled.
Returns ​
Promise<void>
Promise for triggering the MFA verification flow.
ready ​
ready:
boolean
Check whether the PrivyProvider is ready to be used. You should wait for this to be true before using values such as authenticated and user.
sendTransaction ​
sendTransaction: (
input,options?) =>Promise<Object>
Prompts a user to send a transaction using their embedded wallet.
This method will error if the user is not authenticated or does not have an ethereum embedded wallet.
If no chainId is specified as part of the UnsignedTransactionRequest, Privy will default to the embedded wallet's current chain ID.
If the config.embeddedWallets.showWalletUIs property is set to false, the wallet will attempt to send the transaction without prompting the user. Otherwise (the default), Privy will show the user a modal to have them confirm the transaction. This can be customized via the SendTransactionModalUIOptions.
Parameters ​
• input: UnsignedTransactionRequest
UnsignedTransactionRequest transaction to be sent
• options?: Object
• options.address?: string
{optional} address for the embedded wallet signing the message. You should ONLY set this parameter if using imported embedded wallets or multiple HD embedded wallets for the same user. Defaults to the user's embedded wallet at HD index 0.
• options.fundWalletConfig?: FundWalletConfig
FundWalletConfig (optional) Funding configuration to specify chain and funding amount (if enabled), in the case of insufficient funds
• options.uiOptions?: SendTransactionModalUIOptions
SendTransactionModalUIOptions (optional) UI options to customize the transaction request modal
Returns ​
Promise<Object>
Promise for the transaction's hash as a hexadecimal string
hash ​
hash: `0x${string}`
setWalletPassword ​
setWalletPassword: () =>
Promise<Wallet>
@deprecated. Use setWalletRecovery instead.
Set (or reset) a password on a wallet.
This method will error if the user does not have an embedded wallet or if the user exits in the middle of the flow.
Returns ​
Promise<Wallet>
Promise for the Wallet object for the updated embedded wallet
setWalletRecovery ​
setWalletRecovery: (
o?) =>Promise<Wallet>
Prompt the user to enable wallet recovery. Current recovery options include password, Google Drive, and iCloud.
This method will error if the user does not have an embedded wallet, if the user's embedded wallet already has a cloud-based recovery set, or if the user exits in the middle of the flow.
Parameters ​
• o?: SetWalletRecoveryOptions
Returns ​
Promise<Wallet>
Promise for the Wallet object for the updated embedded wallet
signMessage ​
signMessage: (
input,options?) =>Promise<Object>
Prompts a user to sign a message using their embedded wallet using EIP-191's personal_sign method (0x45).
This method will error if the user is not authenticated or does not have an embedded wallet.
If the config.embeddedWallets.showWalletUIs property is set to false, the signature will be computed without prompting the user. Otherwise (the default), Privy will show the user a modal to prompt them for a signature. This can be customized via the SignMessageModalUIOptions.
Parameters ​
• input: Object
• input.message: string
{string} message to be signed
• options?: Object
• options.address?: string
{optional} address for the embedded wallet signing the message. You should ONLY set this parameter if using imported embedded wallets or multiple HD embedded wallets for the same user. Defaults to the user's embedded wallet at HD index 0.
• options.uiOptions?: SignMessageModalUIOptions
SignMessageModalUIOptions (optional) UI options to customize the signature prompt modal
Returns ​
Promise<Object>
Promise for the signature as a string
signature ​
signature:
string
signTransaction ​
signTransaction: (
input,options?) =>Promise<Object>
Prompts a user to sign a transaction using their embedded wallet.
This method will error if the user is not authenticated or does not have an ethereum embedded wallet.
If no chainId is specified as part of the UnsignedTransactionRequest, Privy will default to the embedded wallet's current chain ID.
If the config.embeddedWallets.showWalletUIs property is set to false, the wallet will attempt to sign the transaction without prompting the user. Otherwise (the default), Privy will show the user a modal to have them confirm the transaction. This can be customized via the SendTransactionModalUIOptions.
Parameters ​
• input: UnsignedTransactionRequest
UnsignedTransactionRequest transaction to be signed
• options?: Object
• options.address?: string
{optional} address for the embedded wallet signing the message. You should ONLY set this parameter if using imported embedded wallets or multiple HD embedded wallets for the same user. Defaults to the user's embedded wallet at HD index 0.
• options.uiOptions?: SendTransactionModalUIOptions
SendTransactionModalUIOptions (optional) UI options to customize the transaction request modal
Returns ​
Promise<Object>
Promise for the signature as a hexadecimal string
signature ​
signature: `0x${string}`
signTypedData ​
signTypedData: (
input,options?) =>Promise<Object>
Prompts a user to sign a message using their embedded wallet using EIP-712's eth_signTypedData_v4.
This method will error if the user is not authenticated or does not have an embedded wallet.
Parameters ​
• input: SignTypedDataParams
{SignTypedDataParams} typed data payload to be signed
• options?: Object
• options.address?: string
{optional} address for the embedded wallet signing the message. You should ONLY set this parameter if using imported embedded wallets or multiple HD embedded wallets for the same user. Defaults to the user's embedded wallet at HD index 0.
• options.uiOptions?: SignMessageModalUIOptions
SignMessageModalUIOptions (optional) UI options to customize the signature prompt modal
Returns ​
Promise<Object>
Promise for the signature as a string
signature ​
signature:
string
submit ​
submit: (
mfaMethod,mfaCode) =>Promise<void>
Submit the MFA code for the current user. This will attempt to complete the MFA flow.
This will reject if:
- The verification attempt failed
- The max number of verification attempts has been reached
- The MFA attempt timed out
These errors can be caught and handled accordingly using the error helpers errorIndicatesMfaVerificationFailed, errorIndicatesMaxMfaRetries, errorIndicatesMfaTimeout exported from 'react-auth'.
Parameters ​
• mfaMethod: "sms" | "totp" | "passkey"
• mfaCode: string | PublicKeyCredentialRequestOptionsJSON
{string} The MFA code to submit.
Returns ​
Promise<void>
Promise for the MFA code submission.
submitEnrollmentWithPasskey ​
submitEnrollmentWithPasskey: (
input,options?) =>Promise<void>
Submit the passkey to complete the enrollment process.
Parameters ​
• input: Object
• input.credentialIds: string[]
• options?: Object
• options.removeForLogin?: boolean
(optional) If false, unenrolled passkeys will be kept linked to the user.
Returns ​
Promise<void>
Promise for the MFA code submission.
submitEnrollmentWithSms ​
submitEnrollmentWithSms: (
meta) =>Promise<void>
Submit the MFA code to complete SMS enrollment process.
Parameters ​
• meta: Object
{phoneNumber: string; mfaCode: string} The MFA code and phone number to submit.
• meta.mfaCode: string
• meta.phoneNumber: string
Returns ​
Promise<void>
Promise for the MFA code submission.
submitEnrollmentWithTotp ​
submitEnrollmentWithTotp: (
meta) =>Promise<void>
Submit the MFA code to complete TOTP enrollment process.
Parameters ​
• meta: Object
{mfaCode: string} The MFA code.
• meta.mfaCode: string
Returns ​
Promise<void>
Promise for the MFA code submission.
unenroll ​
unenroll: (
method,options?) =>Promise<void>
Remove the MFA method for the current user.
Parameters ​
• method: "sms" | "totp" | "passkey"
MfaMethod The MFA method to remove for the current user.
• options?: Object
• options.removeForLogin?: boolean
(optional) If false, unenrolled passkeys will be kept linked to the user.
Returns ​
Promise<void>
Promise for removing the MFA method for the current user.
unlinkApple ​
unlinkApple: (
subject) =>Promise<User>
Unlink a Apple social account from a user, by passing the apple subject ID. Note that you can only unlink a social account if the user has at least one other account.
Parameters ​
• subject: string
{string} apple account's subject ID
Returns ​
Promise<User>
Promise for the User object after the provided Apple account has been unlinked
unlinkCrossAppAccount ​
unlinkCrossAppAccount: (
subject) =>Promise<User>
Unlink a cross-app account from a user, by passing the apple subject ID. Note that you can only unlink this account if the user has at least one other account.
Parameters ​
• subject: Object
{string} apple account's subject ID
• subject.subject: string
Returns ​
Promise<User>
Promise for the User object after the provided cross-app account has been unlinked
unlinkDiscord ​
unlinkDiscord: (
subject) =>Promise<User>
Unlink a Discord social account from a user, by passing the discord subject ID. Note that you can only unlink a social account if the user has at least one other account.
Parameters ​
• subject: string
{string} discord account's subject ID
Returns ​
Promise<User>
Promise for the User object after the provided Discord account has been unlinked
unlinkEmail ​
unlinkEmail: (
address) =>Promise<User>
Unlink an email account from a user, by passing the email address. Note that you can only unlink an email account if the user has at least one other account.
Parameters ​
• address: string
{string} email address to be unlinked
Returns ​
Promise<User>
Promise for the User object after the provided email has been unlinked
unlinkFarcaster ​
unlinkFarcaster: (
fid) =>Promise<User>
Unlink a Farcaster account from a user, by passing the FID. Note that you can only unlink a phone account if the user has at least one other account.
Parameters ​
• fid: number
{number} Farcaster ID
Returns ​
Promise<User>
Promise for the User object after the provided Farcaster account has been unlinked
unlinkGithub ​
unlinkGithub: (
subject) =>Promise<User>
Unlink a Github social account from a user, by passing the github subject ID. Note that you can only unlink a social account if the user has at least one other account.
Parameters ​
• subject: string
{string} github account's subject ID
Returns ​
Promise<User>
Promise for the User object after the provided Github account has been unlinked
unlinkGoogle ​
unlinkGoogle: (
subject) =>Promise<User>
Unlink a Google social account from a user, by passing the google subject ID. Note that you can only unlink a social account if the user has at least one other account.
Parameters ​
• subject: string
{string} google account's subject ID
Returns ​
Promise<User>
Promise for the User object after the provided Google account has been unlinked
unlinkInstagram ​
unlinkInstagram: (
subject) =>Promise<User>
Unlink a Instagram social account from a user, by passing the instagram subject ID. Note that you can only unlink a social account if the user has at least one other account.
Parameters ​
• subject: string
{string} instagram account's subject ID
Returns ​
Promise<User>
Promise for the User object after the provided Instagram account has been unlinked
unlinkLinkedIn ​
unlinkLinkedIn: (
subject) =>Promise<User>
Unlink a LinkedIn social account from a user, by passing the linkedin subject ID. Note that you can only unlink a social account if the user has at least one other account.
Parameters ​
• subject: string
{string} linkedin account's subject ID
Returns ​
Promise<User>
Promise for the User object after the provided LinkedIn account has been unlinked
unlinkPasskey ​
unlinkPasskey: (
credentialId) =>Promise<User>
Unlink a Passkey account from a user, by passing the credential ID. Note that you can only unlink a passkey account if the user has at least one other account.
Parameters ​
• credentialId: string
{string} Passkey Credential ID
Returns ​
Promise<User>
Promise for the User object after the provided passkey account has been unlinked
unlinkPhone ​
unlinkPhone: (
phoneNumber) =>Promise<User>
Unlink a phone account from a user, by passing the phone number. Note that you can only unlink a phone account if the user has at least one other account.
Parameters ​
• phoneNumber: string
{string} phone number to be unlinked
Returns ​
Promise<User>
Promise for the User object after the provided phone number has been unlinked
unlinkSpotify ​
unlinkSpotify: (
subject) =>Promise<User>
Unlink a Spotify social account from a user, by passing the spotify subject ID. Note that you can only unlink a social account if the user has at least one other account.
Parameters ​
• subject: string
{string} spotify account's subject ID
Returns ​
Promise<User>
Promise for the User object after the provided Spotify account has been unlinked
unlinkTelegram ​
unlinkTelegram: (
telegramUserId) =>Promise<User>
Unlink a Telegram account from a user, by passing the Telegram subject ID. Note that you can only unlink a social account if the user has at least one other account.
Parameters ​
• telegramUserId: string
{string} Telegram user ID of the linked account
Returns ​
Promise<User>
Promise for the User object after the provided Telegram account has been unlinked
unlinkTiktok ​
unlinkTiktok: (
subject) =>Promise<User>
Unlink a Tiktok social account from a user, by passing the tiktok subject ID. Note that you can only unlink a social account if the user has at least one other account.
Parameters ​
• subject: string
{string} tiktok account's subject ID
Returns ​
Promise<User>
Promise for the User object after the provided Tiktok account has been unlinked
unlinkTwitter ​
unlinkTwitter: (
subject) =>Promise<User>
Unlink a Twitter social account from a user, by passing the twitter subject ID. Note that you can only unlink a social account if the user has at least one other account.
Parameters ​
• subject: string
{string} twitter account's subject ID
Returns ​
Promise<User>
Promise for the User object after the provided Twitter account has been unlinked
unlinkWallet ​
unlinkWallet: (
address) =>Promise<User>
Unlink a wallet account from a user, by passing the public address. Note that you can only unlink a wallet account if the user has at least one other account. If the unlinked wallet was the active one, and more wallets are linked to the user, then we attempt to make the most recently linked wallet active.
Parameters ​
• address: string
{string} wallet address to be unlinked
Returns ​
Promise<User>
Promise for the User object after the provided wallet has been unlinked
updateEmail ​
updateEmail: () =>
void
For users who are authenticated and have already linked an email address, prompts the user to update their email address. This will open the Privy Modal which will guide the user through this action.
Returns ​
void
updatePhone ​
updatePhone: () =>
void
For users who are authenticated and have already linked a phone number, prompts the user to update their phone number. This will open the Privy Modal which will guide the user through this action.
Returns ​
void
user ​
user:
null|User
The user object, or null if the user is not authenticated.