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 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) wallet address to export the private key for
Returns
Promise<void>
Promise that resolves once the user exits the modal
forkSession
forkSession: () =>
Promise<string>
Experimental: This feature is subject to change at any time.
Get a short-lived, one-time-use token to start a new Privy session from the existing authenticated session. Raises an exception if the current session was already forked from a previous session.
Returns
Promise<string>
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.
getEthereumProvider
getEthereumProvider: () =>
EIP1193Provider
Returns
Deprecated
Deprecated: This method will be deprecated and should be replaced by calling getEthereumProvider directly on the ConnectedWallet objects returned by the useWallets hook, e.g.
tsx
const {wallets} = useWallets();
const provider = await wallets[0].getEthereumProvider();Gets an EIP-1193-compatible provider from the user's wallet, if the user has connected one.
You may then use the Ethereum Javascript API syntax to send JSON-RPC requests to the user's wallet.
getEthersProvider
getEthersProvider: () =>
Web3Provider
Returns
Web3Provider
Deprecated
Deprecated: This method will be deprecated and should be replaced by calling getEthersProvider directly on the ConnectedWallet objects returned by the useWallets hook, e.g.
tsx
const {wallets} = useWallets();
const provider = await wallets[0].getEthersProvider();Get an ethers.js-compatible provider from the user's wallet, if the user has connected one.
getWeb3jsProvider
getWeb3jsProvider: () =>
AbstractProvider
Returns
AbstractProvider
Deprecated
Deprecated: This feature will be deprecated and should be replaced by calling getWeb3jsProvider directly on the ConnectedWallet objects returned by the useWallets hook, e.g.
tsx
const {wallets} = useWallets();
const provider = await wallets[0].getWeb3jsProvider();Get a web3.js-compatible provider from the user's wallet, if the user has connected one.
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: () =>
void
For users who are authenticated, prompts the user to link a Telegram account This will directly initiate the auth flow for Telegram.
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: () =>
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.
Returns
void
login
login: (
options?) =>void
Opens the Privy login modal and prompts the user to login.
Parameters
• options?: MouseEvent<any, any> | RuntimeLoginOverridableOptions
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.
sendSolanaTransaction
sendSolanaTransaction: (
transaction,connection,uiOptions?,transactionOptions?) =>Promise<SolanaTransactionReceipt>
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 a solana embedded wallet.
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
• transaction: SupportedSolanaTransaction
{SupportedSolanaTransaction} transaction to be sent
• connection: Connection
{Connection} connection to the Solana network
• uiOptions?: SendTransactionModalUIOptions
SendTransactionModalUIOptions (optional) UI options to customize the transaction request modal
• transactionOptions?: SendTransactionOptions
[SendTransactionOptions]([object Object]) (optional) Transaction options to customize the transaction request
Returns
Promise<SolanaTransactionReceipt>
sendTransaction
sendTransaction: (
data,uiOptions?,fundWalletConfig?,address?) =>Promise<TransactionReceipt>
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
• data: UnsignedTransactionRequest
UnsignedTransactionRequest transaction to be sent
• uiOptions?: SendTransactionModalUIOptions
SendTransactionModalUIOptions (optional) UI options to customize the transaction request modal
• fundWalletConfig?: FundWalletConfig
FundWalletConfig (optional) Funding configuration to specify chain and funding amount (if enabled), in the case of insufficient funds
• 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.
Returns
Promise<TransactionReceipt>
Promise for the transaction's TransactionReceipt
setActiveWallet
setActiveWallet: (
address) =>Promise<void>
Parameters
• address: string
Returns
Promise<void>
Deprecated
Deprecated: This feature will be removed and behaves the same as connectWallet(). Instead, please interact with the wallets array directly.
Note that when you connect a new wallet, it becomes first in the wallets array.
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: (
message,uiOptions?,address?) =>Promise<string>
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
• message: string
{string} message to be signed
• uiOptions?: SignMessageModalUIOptions
SignMessageModalUIOptions (optional) UI options to customize the signature prompt modal
• 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.
Returns
Promise<string>
Promise for the signature as a string
signTypedData
signTypedData: (
typedData,uiOptions?,address?) =>Promise<string>
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
• typedData: SignTypedDataParams
• uiOptions?: SignMessageModalUIOptions
SignMessageModalUIOptions (optional) UI options to customize the signature prompt modal
• 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.
Returns
Promise<string>
Promise for the signature as a 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: (
meta) =>Promise<void>
Submit the passkey to complete the enrollment process.
Parameters
• meta: Object
{credentialIds: string[]} The passkey credentialIds to enroll in MFA.
• meta.credentialIds: string[]
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) =>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.
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.
walletConnectors
walletConnectors:
null|ConnectorManager
Deprecated
Deprecated: This feature will be removed and should be replaced by the useWallets hook.
Get the ConnectorManager object This shouldn't need to be used directly unless creating a plugin, like a WAGMI plugin