Using custom UIs

​

Configuring MFA to be used with custom UIs

If you plan to use your own custom UIs for wallet MFA, set the mfa.noPromptOnMfaRequired field to true in the Privy provider.

function MyApp({Component, pageProps}: AppProps) {
  return (
    <>
      <PrivyProvider
        appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
        config={{
          mfa: {
            // Defaults to 'false'
            noPromptOnMfaRequired: true,
          },
          ...insertTheRestOfYourConfig,
        }}
      >
        <Component {...pageProps} />
      </PrivyProvider>
    </>
  );
}

This will configure Privy to not show its default UIs for wallet MFA, and instead rely on your custom implementation.

​

Enrolling in MFA

To enroll your users in MFA, use the hook from Privy. Currently, users can enroll in three MFA methods:

• SMS, where users authenticate with a 6-digit MFA code sent to their phone number
• TOTP, where users authenticate with a 6-digit MFA code from an authentication app, like Authy or Google Authenticator
• Passkey, where users verify with a previously registered passkey, generally through biometric authentication on their device

​

SMS

To enroll your users in MFA with SMS, use the and methods returned by the hook:

const {initEnrollmentWithSms, submitEnrollmentWithSms} = useMfaEnrollment();

First, initiate enrollment by prompting your user to enter the phone number they’d like to use for MFA. Then, call Privy’s method. As a parameter to this , pass a JSON object with a field that contains the user’s provide phone number as a string.

// Prompt the user for their phone number
const phoneNumberInput = 'insert-phone-number-from-user';
// Send an enrollment code to their phone number
await initEnrollmentWithSms({phoneNumber: phoneNumberInput});

Once is called with a valid , Privy will then send a 6-digit MFA enrollment code to the provided number. This method returns a Promise that will resolve to void if the code was successfully sent, or will reject with an error if there was an error sending the code (e.g. invalid phone number).

Next, prompt the user to enter the 6-digit code that was sent to their phone number, and use the method to complete enrollment of that phone number. As a parameter to , you must pass a JSON object with both the original that the user enrolled, and the they received at that number.

// Prompt the user for the code sent to their phone number
const mfaCodeInput = 'insert-mfa-code-received-by-user';
await submitEnrollmentWithSms({
  phoneNumber: phoneNumberInput, // From above
  mfaCode: mfaCodeInput,
});

​

TOTP

To enroll your users in MFA with TOTP, use the and methods returned by the hook:

const {initEnrollmentWithTotp, submitEnrollmentWithTotp} = useMfaEnrollment();

First, initiate enrollment by calling Privy’s method with no parameters. This method returns a Promise for an and that the user will need in order to complete enrollment.

const {authUrl, secret} = await initEnrollmentWithTotp();

Then, to have the user enroll, you can either:

• display the TOTP as a QR code to the user, and prompt them to scan it with their TOTP client (commonly, a mobile app like Google Authenticator or Authy)
• allow the user to copy the TOTP and paste it into their TOTP client

Once your user has successfully scanned the QR code, an enrollment code for Privy will appear within their TOTP client. Prompt the user to enter this code in your app, and call Privy’s method. As a parameter to , pass a JSON object with an field that contains the MFA code from the user as a string.

const mfaCodeInput = 'insert-mfa-code-from-user-totp-app'; // Prompt the user for the code in their TOTP app
await submitEnrollmentWithTotp({mfaCode: mfaCodeInput});

​

Passkey

To enroll your users in MFA with passkeys, use the and methods returned by the hook:

const {initEnrollmentWithPasskey, submitEnrollmentWithPasskey} = useMfaEnrollment();

First, initiate enrollment by calling Privy’s method with no parameters. This method returns a Promise that will resolve to void indicating success.

await initEnrollmentWithPasskey();

Then, to have the user enroll, you must call Privy’s submitEnrollmentWithPasskey method with a list of the user’s passkey account credentialIds. You can find this list by querying the user’s linkedAccounts array for all accounts of type: 'passkey':

const {user} = usePrivy();

// ...

const credentialIds = user.linkedAccounts
  .filter((account): account is PasskeyWithMetadata => account.type === 'passkey')
  .map((x) => x.credentialId);

await submitEnrollmentWithPasskey({credentialIds});

​

Completing MFA

Once users have successfully enrolled in MFA with Privy, they will be required to complete MFA whenever the private key for their embedded wallet must be used. This includes signing messages and transactions, recovering the embedded wallet on new devices, exporting the wallet’s private key, and setting a password on the wallet.

To ensure users can complete MFA when required, your app must do the following:

1. Set up a flow to guide the user through completing MFA when required.
2. Register an event listener to configure Privy to invoke the flow from step (1) whenever MFA is required.

​

Guiding the user through MFA

To set up a flow to have the user complete MFA, use Privy’s hook.

const {init, submit, cancel} = useMfa();

This flow has three core components:

1. Requesting an MFA code be sent to the user’s MFA method ()
2. Submitting the MFA code provided by the user ()
3. Cancelling an in-progress MFA flow ()

​

Requesting an MFA challenge

To request an MFA challenge for the current user, call the method from the hook, passing the user’s desired MFA method ('sms', 'totp', or 'passkey') as a parameter.

const selectedMfaMethod = 'sms'; // Must be 'sms', 'totp' or 'passkey'
await init(selectedMfaMethod);

The method will then prepare an MFA challenge for the desired MFA method, and returns a Promise that resolves if the challenge was successfully created, and rejects with an error if there was an issue.

• If the MFA method is 'sms', the user will receive an SMS with their MFA code at the phone number they originally enrolled.
• If the MFA method is 'totp', the user will receive the MFA code within their authenticator app.
• If the MFA method is 'passkey', init will return an object with options to pass to the native passkey system

​

Submitting the MFA verification

const mfaCode = 'insert-mfa-code-from-user';
await submit(selectedMfaMethod, mfaCode);

const mfaCode = 'insert-mfa-code-from-user';
await submit(selectedMfaMethod, mfaCode);

const options = await init('passkey');

// Submit will trigger the system's native passkey prompt
await submit('passkey', options);

​

Cancelling the MFA flow

After has been called and the corresponding call has not yet occurred, the user may cancel their in-progress MFA flow if they wish.

To cancel the current MFA flow, call the method from the hook.

cancel();

​

Registering an event listener

Once you’ve set up your app’s logic for guiding a user to complete MFA, you lastly need to configure Privy to invoke this logic whenever MFA is required by the user’s embedded wallet.

To set up this configuration, use Privy’s hook. As a parameter to , you must pass a JSON object with an callback, described below.

​

onMfaRequired

Privy will invoke the callback you set whenever the user is required to complete MFA to use the embedded wallet. When this occurs, any use of the embedded wallet will be “paused” until the user has successfully completed MFA with Privy.

In this callback, you should invoke your app’s logic for guiding through completing MFA (done via the hook, as documented above). Within this callback, you can also access an parameter that contains a list of available MFA methods that the user has enrolled in ('sms' and/or 'totp' and/or 'passkey').

import {useRegisterMfaListener, MfaMethod} from '@privy-io/react-auth';

import {MFAModal} from '../components/MFAModal';

export const MFAProvider = ({children}: {children: React.ReactNode}) => {
  const [isMfaModalOpen, setIsMfaModelOpen] = useState(false);
  const [mfaMethods, setMfaMethods] = useState<MfaMethod[]>([]);

  useRegisterMfaListener({
    // Privy will invoke this whenever the user is required to complete MFA
    onMfaRequired: (methods) => {
      // Update app's state with the list of available MFA methods for the user
      setMfaMethods(methods);
      // Open MFA modal to allow user to complete MFA
      setIsMfaModalOpen(true);
    },
  });

  return (
    <div>
      {/* This `MFAModal` component includes all logic for completing the MFA flow with Privy's `useMfa` hook */}
      <MFAModal isOpen={isMfaModalOpen} setIsOpen={setIsMfaModalOpen} mfaMethods={mfaMethods} />
      {children}
    </div>
  );
};

import {useRegisterMfaListener, MfaMethod} from '@privy-io/react-auth';

import {MFAModal} from '../components/MFAModal';

export const MFAProvider = ({children}: {children: React.ReactNode}) => {
  const [isMfaModalOpen, setIsMfaModelOpen] = useState(false);
  const [mfaMethods, setMfaMethods] = useState<MfaMethod[]>([]);

  useRegisterMfaListener({
    // Privy will invoke this whenever the user is required to complete MFA
    onMfaRequired: (methods) => {
      // Update app's state with the list of available MFA methods for the user
      setMfaMethods(methods);
      // Open MFA modal to allow user to complete MFA
      setIsMfaModalOpen(true);
    },
  });

  return (
    <div>
      {/* This `MFAModal` component includes all logic for completing the MFA flow with Privy's `useMfa` hook */}
      <MFAModal isOpen={isMfaModalOpen} setIsOpen={setIsMfaModalOpen} mfaMethods={mfaMethods} />
      {children}
    </div>
  );
};

​

Handling errors with code submission

When both enrolling in and completing MFA, Privy sends a 6-digit code to the user’s selected MFA method, that the user must submit to Privy in order to verify their identity.

When submitting this MFA code, Privy may respond with an error if the code is incorrect, if the user has reached the maximum number of attempts for this MFA flow, or if the MFA flow has timed out. If the user enters in an incorrect code (e.g. by mistyping), the user is allowed to retry code submission up to a maximum of four attempts.

To simplify handling errors with MFA code submission, Privy provides the following helper functions to parse errors raised by the MFA code submission methods listed above. Each of these functions accepts the raw raised as a parameter, and returns a Boolean indicating if the error meets a certain condition:

• : indicates the user entered an incorrect MFA code
• indicates has reached the maximum number of attempts for this MFA flow, and that a new MFA code must be requested via
• indicates that the current MFA code has expired, and that a new MFA code must be requested via

As an example, to handle errors raised by , you might use these helpers like so:

try {
  // Errors from `submitEnrollmentWithSms` and `submitEnrollmentWithTotp` can be handled similarly
  await submit('insert-mfa-code', 'insert-mfa-method');
} catch (e) {
  if (errorIndicatesMfaVerificationFailed(e)) {
    console.error('Incorrect MFA code, please try again.');
    // Allow the user to re-enter the code and call `submit` again
  } else if (errorIndicatesMfaMaxAttempts(e)) {
    console.error('Maximum MFA attempts reached, please request a new code.');
    // Allow the user to request a new code with `init`
  } else if (errorIndicatesMfaTimeout(e)) {
    console.error('MFA code has expired, please request a new code.');
    // Allow the user to request a new code with `init`
  }
}

​

Enrollment flows with custom UIs in Expo

To enroll your users in MFA, use the and methods returned by the hook:

const {initMfaEnrollment, submitMfaEnrollment} = useMfaEnrollment();

Currently, users can enroll in three MFA methods:

• , where users authenticate with a 6-digit MFA code sent to their phone number
• , where users authenticate with a 6-digit MFA code from an authentication app, like Authy or Google Authenticator
• , where users verify with a previously registered passkey, generally through biometric authentication on their device

​

SMS

First, initiate enrollment by prompting your user to enter the phone number they’d like to use for MFA. Then, call Privy’s method with the appropriate parameters:

// Prompt the user for their phone number
const phoneNumberInput = 'insert-phone-number-from-user';
// Send an enrollment code to their phone number
await initMfaEnrollment({method: 'sms', phoneNumber: phoneNumberInput});

Once is called with a valid , Privy will then send a 6-digit MFA enrollment code to the provided number.

Next, prompt the user to enter the 6-digit code that was sent to their phone number, and use the method to complete enrollment:

// Prompt the user for the code sent to their phone number
const mfaCodeInput = 'insert-mfa-code-received-by-user';
await submitMfaEnrollment({
  method: 'sms',
  phoneNumber: phoneNumberInput, // From above
  code: mfaCodeInput,
});

​

TOTP

First, initiate enrollment by calling Privy’s method with a JSON parameter of :

const {authUrl} = await initMfaEnrollment({method: 'totp'});

Then, to have the user enroll, you can display the TOTP as a QR code to the user, and prompt them to scan it with their TOTP client.

Once your user has successfully linked into their TOTP application, prompt the user to enter the code in your app, and call Privy’s method:

const mfaCodeInput = 'insert-mfa-code-from-user-totp-app'; // Prompt the user for the code in their TOTP app
await submitMfaEnrollment({method: 'totp', mfaCode: mfaCodeInput});

​

Passkey

First, initiate enrollment by calling Privy’s method with a JSON parameter of :

await initMfaEnrollment({method: 'passkey'});

Then, to have the user enroll, you must call Privy’s submitMfaEnrollment method with a list of the user’s passkey account credentialIds:

const {user} = usePrivy();

// ...

const credentialIds = user.linked_accounts
  .filter((account): account is PasskeyWithMetadata => account.type === 'passkey')
  .map((x) => x.credentialId);

await submitMfaEnrollment({method: 'passkey', credentialIds});

​

Completing MFA with custom UIs in Expo

To set up a flow to have the user complete MFA, use Privy’s hook:

const {init, submit, cancel} = useMfa();

This flow has three core components:

1. Requesting an MFA code be sent to the user’s MFA method ()
2. Submitting the MFA code provided by the user ()
3. Cancelling an in-progress MFA flow ()

​

Requesting and submitting an MFA challenge

const selectedMfaMethod = 'sms'; // Must be 'sms', 'totp' or 'passkey'
await init({method: selectedMfaMethod});

// After user enters the code
const mfaCode = 'insert-mfa-code-from-user';
await submit({method: selectedMfaMethod, mfaCode});

const selectedMfaMethod = 'sms'; // Must be 'sms', 'totp' or 'passkey'
await init({method: selectedMfaMethod});

// After user enters the code
const mfaCode = 'insert-mfa-code-from-user';
await submit({method: selectedMfaMethod, mfaCode});

const options = await init({method: 'passkey'});

// Submit will trigger the system's native passkey prompt
await submit({method: 'passkey', mfaCode: options});

When invoked, returns a Promise that resolves to void if the user has successfully completed MFA, or rejects with an error if there was an issue completing MFA.

​

Cancelling the MFA flow

To cancel the current MFA flow, call the method from the hook:

cancel();

​

Registering an event listener

To set up this configuration, use Privy’s hook:

import {useRegisterMfaListener, MfaMethod} from '@privy-io/expo';

import {MFAModal} from '../components/MFAModal';

export const MFAProvider = ({children}: {children: React.ReactNode}) => {
  const [isMfaModalOpen, setIsMfaModelOpen] = useState(false);
  const [mfaMethods, setMfaMethods] = useState<MfaMethod[]>([]);

  useRegisterMfaListener({
    // Privy will invoke this whenever the user is required to complete MFA
    onMfaRequired: (methods) => {
      // Update app's state with the list of available MFA methods for the user
      setMfaMethods(methods);
      // Open MFA modal to allow user to complete MFA
      setIsMfaModalOpen(true);
    },
  });

  return (
    <View>
      {/* This `MFAModal` component includes all logic for completing the MFA flow with Privy's `useMfa` hook */}
      <MFAModal isOpen={isMfaModalOpen} setIsOpen={setIsMfaModalOpen} mfaMethods={mfaMethods} />
      {children}
    </View>
  );
};

​

Managing MFA methods

Privy also allows users to also delete MFA methods via the method returned from the hook:

import {useMfaEnrollment} from '@privy-io/expo';

export default function MfaUnenrollment() {
  const {unenrollWithSms, unenrollWithTotp} = useMfaEnrollment();

  return (
    <YStack>
      <Button onClick={() => unenrollMfa({method: 'sms'})}>
        <Text>Unenroll SMS</Text>
      </Button>
      <Button onClick={() => unenrollMfa({method: 'totp'})}>
        <Text>Unenroll TOTP</Text>
      </Button>
      <Button onClick={() => unenrollMfa({method: 'passkey'})}>
        <Text>Unenroll passkey</Text>
      </Button>
    </YStack>
  );
}

<Button onClick={() => unenrollMfa({method: 'passkey', removeForLogin: false})}>
  <Text>Unenroll passkey, keep as login method</Text>
</Button>