Passkeys

To authenticate your users with a passkey, you can use the useLoginWithPasskey hook. The useLoginWithPasskey hook returns:

• loginWithPasskey: a method that starts the passkey login flow
• state: a variable that tracks the login flow state

Example usage

As an example, you might set up a LoginWithPasskey component for your app that uses these methods, like below:

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

export default function LoginWithPasskey() {
  const {state, loginWithPasskey} = useLoginWithPasskey();

  return <button onClick={loginWithPasskey}>Log in with Passkey</button>;
}

Tracking login flow state

The state variable returned from the useLoginWithPasskey hook will always be one of the following values.

type PasskeyFlowState =
  | {status: 'initial'}
  | {status: 'error'; error: Error | null}
  | {status: 'generating-challenge'}
  | {status: 'awaiting-passkey'}
  | {status: 'submitting-response'}
  | {status: 'done'};

Learn more about conditional rendering with the state variable in the state guide.

Unlinking Passkeys

Passkeys can be unlinked as login methods by using the unlinkPasskey method on the usePrivy hook. See our guide on unlinking accounts for more details.

Passkeys for MFA

Passkeys can also be used as an MFA method, which changes how unlinking them as a login method works.

By default, when a passkey is unlinked as a login method, it will also be unenrolled from MFA. The reverse is also true, and when a passkey is unenrolled from MFA it is also unlinked as a login method.

This behavior, however, can be modified by setting the shouldUnlinkOnUnenrollMfa and shouldUnenrollMfaOnUnlink configuration flags on the PrivyProvider.

<PrivyProvider
  appId="your-privy-app-id"
  config={{
    ...theRestOfYourConfig,
    passkeys: {
      // Set this to `false` if you wish to keep the passkey as a login method after unenrolling from MFA.
      shouldUnlinkOnUnenrollMfa: false,
      // Set this to `false` if you wish to keep the passkey as an MFA method after unlinking it.
      shouldUnenrollMfaOnUnlink: false,
    },
  }}
>
  {/* your app's content */}
</PrivyProvider>

Signing up with a passkey

INFO

Passkey sign up is not allowed by default, and needs to be explicitly enabled in the Dashboard, under the "Passkeys" config in "Login Methods"

Unlike other login methods, allowing user to sign up with a passkey, creating a brand new account, requires an explicit decision, by using the useSignupWithPasskey hook instead.

import {useSignupWithPasskey} from '@privy-io/react-auth';
...
const {signupWithPasskey} = useSignupWithPasskey();

Use the signupWithPasskey method to prompt your user to create a brand new passkey and a new account on your application.

When signupWithPasskey is invoked, the user will receive a system prompt for creating a new passkey. After that, Privy will use the newly created passkey to authenticate the user.

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

export default function SignupWithPasskey() {
  const {state, signupWithPasskey} = useSignupWithPasskey();

  return <button onClick={signupWithPasskey}>Sign up with Passkey</button>;
}

Just like the useLoginWithPasskey hook, useSignupWithPasskey also returns a state property for doing conditional rendering.

WARNING

Accounts that signed up via a Passkey have no other login method available by default. This means that losing the passkey means they will lose access to their account.