Skip to content

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?: Object

options.suggestedAddress?: string

{string} (optional) wallet address that you wish to prompt the user to explicitly connect, if included

Returns

void


createWallet

createWallet: () => 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.

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: () => Promise<void>

Shows the user a Privy modal, from which they can copy their embedded wallet's private key 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.

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

EIP1193Provider

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: string

secret

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: () => void

Opens the Privy login modal and prompts the user to login.

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: (data, uiOptions?, fundWalletConfig?) => 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 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.noPromptOnSignature property is set to true, 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) Configuration surrounding funding the wallet (if enabled), in the case of insufficient funds

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: () => 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.

Returns

Promise<Wallet>

Promise for the Wallet object for the updated embedded wallet


signMessage

signMessage: (message, uiOptions?) => 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.noPromptOnSignature property is set to true, 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

Returns

Promise<string>

Promise for the signature as a string


signTypedData

signTypedData: (typedData, uiOptions?) => 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

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


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


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