Passkey enrollment

Enrolling in MFA does not automatically verify the user for wallet operations. Once enrolled, subsequent wallet actions will require MFA verification. See the verification guides for how to complete MFA verification.

Enroll users in MFA using passkeys, where they verify with a previously registered passkey through biometric authentication on their device.

In order to use passkeys as an MFA method, make sure a valid passkey is linked to the user. You can set this up by following the steps here!

React
React Native
Swift

Setup

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

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

const {initEnrollmentWithPasskey, submitEnrollmentWithPasskey} = useMfaEnrollment();

Initiating enrollment

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

await initEnrollmentWithPasskey();

Completing enrollment

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

import {usePrivy} from '@privy-io/react-auth';

const {user} = usePrivy();

// ...

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

await submitEnrollmentWithPasskey({credentialIds});

See an end-to-end example of enrolling users in MFA with passkeys

The component below serves as a reference implementation for how to enroll your users in MFA with passkeys!

Example enrolling passkeys for MFA

import {useMfaEnrollment, usePrivy} from '@privy-io/react-auth';

export default function MfaEnrollmentWithPasskey() {
  const {user} = usePrivy();
  const {initEnrollmentWithPasskey, submitEnrollmentWithPasskey} = useMfaEnrollment();

  const handleEnrollmentWithPasskey = async () => {
    await initEnrollmentWithPasskey();

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

    await submitEnrollmentWithPasskey({credentialIds});
  };

  return (
    <div>
      <div>Enable your passkeys for MFA</div>
      {user.linkedAccounts
        .filter((account): account is PasskeyWithMetadata => account.type === 'passkey')
        .map((account) => (
          <div key={account.id}>{account.credentialId}</div>
        ))}
      <button onClick={handleEnrollmentWithPasskey}>Enroll</button>
    </div>
  );
}

Setup

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

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

const {initMfaEnrollment, submitMfaEnrollment} = useMfaEnrollment();

Initiating enrollment

First, initiate enrollment by calling Privy’s initMfaEnrollment method with a JSON parameter of {method: 'passkey'}:

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

Completing enrollment

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

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

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});

See an end-to-end example of enrolling users in MFA with passkeys

The component below serves as a reference implementation for how to enroll your users in MFA with passkeys!

Example enrolling passkeys for MFA

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

export default function MfaEnrollmentWithPasskey() {
  const {user} = usePrivy();
  const {initMfaEnrollment, submitMfaEnrollment} = useMfaEnrollment();

  const handleEnrollmentWithPasskey = async () => {
    await initMfaEnrollment({method: 'passkey'});

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

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

  return (
    <YStack>
      <Text>Enable your passkeys for MFA</Text>
      {user.linkedAccounts
        .filter((account): account is PasskeyWithMetadata => account.type === 'passkey')
        .map((account) => (
          <Text>ID: {account.id} {' '} Credential ID: {account.credentialId}</Text>
        ))}
      {// Initialize and submit the passkey credentials for MFA enrollment in one step }
      <Button onPress={handleEnrollmentWithPasskey}>
        <Text>Enroll</Text>
      </Button>
    </YStack>
  );
}

Enrolling passkeys

To enroll passkeys as an MFA method, call Privy’s submit method with the list of passkey credential IDs that should be enabled for MFA. You can find the credential IDs from the user’s linked accounts:

guard let user = await privy.getUser() else { return }

// Get credential IDs from linked passkey accounts
let credentialIds = user.linkedAccounts
    .compactMap { account -> String? in
        if case .passkey(let passkey) = account {
            return passkey.credentialId
        }
        return nil
    }

// Submit credential IDs to complete enrollment
let updatedUser = try await user.mfa.passkeys.enroll.submit(credentialIds: credentialIds)

// The updated user object will contain the newly enrolled mfaMethod
print(updatedUser.mfaMethods)

Using Privy authentication

Using your own authentication

Setup

Initiating enrollment

Completing enrollment

Setup

Initiating enrollment

Completing enrollment

Enrolling passkeys

Using Privy authentication

Using your own authentication

​Setup

​Initiating enrollment

​Completing enrollment

​Setup

​Initiating enrollment

​Completing enrollment

​Enrolling passkeys

Setup

Initiating enrollment

Completing enrollment

Setup

Initiating enrollment

Completing enrollment

Enrolling passkeys